proteum 2.1.0-5 → 2.1.1

package/cli/commands/dev.ts

@@ -5,6 +5,8 @@
 // Npm
 import path from 'path';
 import { spawn, ChildProcess } from 'child_process';
+import fs from 'fs-extra';
+import type { FSWatcher } from 'fs';
 
 // Cor elibs
 import cli from '..';
@@ -31,7 +33,7 @@ import { app, App } from '../app';
 ----------------------------------*/
 
 // Watch rules shared by the dev compiler and hot reload gate.
-const ignoredWatchPathPatterns = /(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)|(\.proteum\/)/;
+const ignoredWatchPathPatterns = /(node_modules\/(?!proteum\/))|(\.generated\/)|(\.cache\/)|(\.proteum\/)|(\/var\/traces\/)/;
 const hotReloadableServerPathPatterns = [
     /^client\/pages\//,
     /^client\/components\//,
@@ -50,6 +52,7 @@ let cp: ChildProcess | undefined = undefined;
 let devSessionStopping = false;
 let appProcessOperation: Promise<void> = Promise.resolve();
 type TDevWatching = ReturnType<Awaited<ReturnType<Compiler['create']>>['watch']>;
+type TIndexedSourceWatching = { close: () => Promise<void> };
 
 /*----------------------------------
 - HELPERS
@@ -110,6 +113,22 @@ const createIgnoredWatchPattern = (outputPaths: string[]) =>
 const getDevAppName = (app: App) =>
     app.identity.web?.fullTitle || app.identity.web?.title || app.identity.name || app.packageJson.name || app.paths.root;
 
+const cleanupPersistedDevTraces = async (app: App) => {
+    const tracesRoot = path.join(app.paths.root, 'var', 'traces');
+    if (!(await fs.pathExists(tracesRoot))) return;
+
+    const entries = await fs.readdir(tracesRoot);
+    const removableEntries = entries.filter((entry) => entry !== 'exports');
+    if (removableEntries.length === 0) return;
+
+    await Promise.all(removableEntries.map((entry) => fs.remove(path.join(tracesRoot, entry))));
+
+    const remainingEntries = await fs.readdir(tracesRoot).catch(() => []);
+    if (remainingEntries.length === 0) {
+        await fs.remove(tracesRoot);
+    }
+};
+
 const signalAppProcess = (child: ChildProcess, signal: NodeJS.Signals) => {
     try {
         if (process.platform !== 'win32' && child.pid !== undefined) {
@@ -238,6 +257,78 @@ function normalizeWatchPath(watchPath: string) {
     return path.resolve(watchPath).replace(/\\/g, '/').replace(/\/$/, '');
 }
 
+const indexedSourceWatchRules: { compilerName: 'server'; root: () => string; relativePathPattern: RegExp }[] = [
+    { compilerName: 'server', root: () => app.paths.root, relativePathPattern: /^commands(?:\/|$)/ },
+    { compilerName: 'server', root: () => cli.paths.core.root, relativePathPattern: /^commands(?:\/|$)/ },
+];
+
+const closeFsWatcher = async (watcher: FSWatcher) => {
+    await new Promise<void>((resolve) => {
+        watcher.once('close', () => resolve());
+        watcher.close();
+    });
+};
+
+const createIndexedSourceWatching = ({
+    compiler,
+    watching,
+}: {
+    compiler: Compiler;
+    watching: TDevWatching;
+}): TIndexedSourceWatching => {
+    const watchers: FSWatcher[] = [];
+    const pendingChanges = new Map<'server', Set<string>>();
+    let invalidateTimer: NodeJS.Timeout | undefined;
+
+    const flushInvalidate = () => {
+        invalidateTimer = undefined;
+
+        for (const [compilerName, changedFiles] of pendingChanges) {
+            compiler.noteManualModifiedFiles(compilerName, [...changedFiles]);
+        }
+
+        pendingChanges.clear();
+        logVerbose('Indexed source files changed. Invalidating the dev compiler to refresh generated artifacts.');
+        watching.invalidate();
+    };
+
+    const queueInvalidate = (compilerName: 'server', filepath: string) => {
+        const normalizedFilepath = normalizeWatchPath(filepath);
+        const changedFiles = pendingChanges.get(compilerName) || new Set<string>();
+
+        changedFiles.add(normalizedFilepath);
+        pendingChanges.set(compilerName, changedFiles);
+
+        if (invalidateTimer) return;
+        invalidateTimer = setTimeout(flushInvalidate, 40);
+    };
+
+    for (const watchRule of indexedSourceWatchRules) {
+        const rootPath = watchRule.root();
+
+        watchers.push(
+            fs.watch(rootPath, { recursive: true }, (eventType, filename) => {
+                const relativePath = typeof filename === 'string' ? filename.replace(/\\/g, '/').replace(/^\.\//, '') : '';
+                if (relativePath && !watchRule.relativePathPattern.test(relativePath)) return;
+                if (eventType !== 'rename' && relativePath) return;
+
+                queueInvalidate(watchRule.compilerName, relativePath ? path.join(rootPath, relativePath) : rootPath);
+            }),
+        );
+    }
+
+    return {
+        close: async () => {
+            if (invalidateTimer) {
+                clearTimeout(invalidateTimer);
+                invalidateTimer = undefined;
+            }
+
+            await Promise.all(watchers.map((watcher) => closeFsWatcher(watcher)));
+        },
+    };
+};
+
 /*----------------------------------
 - MAIN PROCESS
 ----------------------------------*/
@@ -341,6 +432,7 @@ export const run = async () => {
             logVerbose('Watch callback. No compiler changes were tracked.');
         },
     );
+    const indexedSourceWatching = createIndexedSourceWatching({ compiler, watching });
 
     let shuttingDownPromise: Promise<void> | undefined;
 
@@ -350,9 +442,11 @@ export const run = async () => {
         devSessionStopping = true;
         shuttingDownPromise = (async () => {
             logVerbose('Stopping the Proteum dev session ...', reason);
+            await indexedSourceWatching.close();
             await closeWatching(watching);
             compiler.dispose();
             await stopApp(reason);
+            await cleanupPersistedDevTraces(app);
             await devEventServer.close();
         })();
 

package/cli/commands/doctor.ts

@@ -1,12 +1,7 @@
-import path from 'path';
-
 import cli from '..';
 import Compiler from '../compiler';
-import {
-    readProteumManifest,
-    type TProteumManifest,
-    type TProteumManifestDiagnostic,
-} from '../compiler/common/proteumManifest';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
+import { buildDoctorResponse, renderDoctorHuman } from '@common/dev/diagnostics';
 
 const allowedDoctorArgs = new Set(['json', 'strict']);
 
@@ -24,43 +19,6 @@ const validateDoctorArgs = () => {
     }
 };
 
-const normalizePath = (value: string) => value.replace(/\\/g, '/');
-
-const formatFilepath = (manifest: TProteumManifest, filepath: string) => {
-    const normalizedFilepath = normalizePath(filepath);
-    const normalizedAppRoot = normalizePath(manifest.app.root);
-    const normalizedCoreRoot = normalizePath(manifest.app.coreRoot);
-
-    if (normalizedFilepath === normalizedAppRoot) return '.';
-    if (normalizedFilepath.startsWith(normalizedAppRoot + '/'))
-        return normalizePath(path.relative(normalizedAppRoot, normalizedFilepath)) || '.';
-
-    if (normalizedFilepath === normalizedCoreRoot) return 'node_modules/proteum';
-    if (normalizedFilepath.startsWith(normalizedCoreRoot + '/'))
-        return normalizePath(path.join('node_modules/proteum', path.relative(normalizedCoreRoot, normalizedFilepath)));
-
-    return normalizedFilepath;
-};
-
-const formatLocation = (diagnostic: TProteumManifestDiagnostic) =>
-    diagnostic.sourceLocation ? `:${diagnostic.sourceLocation.line}:${diagnostic.sourceLocation.column}` : '';
-
-const renderGroup = (manifest: TProteumManifest, diagnostics: TProteumManifestDiagnostic[], title: string) => {
-    if (diagnostics.length === 0) return `${title}\n- none`;
-
-    return [
-        title,
-        ...diagnostics.map((diagnostic) => {
-            const related =
-                diagnostic.relatedFilepaths && diagnostic.relatedFilepaths.length > 0
-                    ? ` related=${diagnostic.relatedFilepaths.map((filepath) => formatFilepath(manifest, filepath)).join(',')}`
-                    : '';
-
-            return `- ${diagnostic.code} ${diagnostic.message} source=${formatFilepath(manifest, diagnostic.filepath)}${formatLocation(diagnostic)}${related}`;
-        }),
-    ].join('\n');
-};
-
 export const run = async (): Promise<void> => {
     validateDoctorArgs();
 
@@ -68,41 +26,17 @@ export const run = async (): Promise<void> => {
     await compiler.refreshGeneratedTypings();
 
     const manifest = readProteumManifest(cli.paths.appRoot);
-    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error');
-    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning');
+    const response = buildDoctorResponse(manifest, cli.args.strict === true);
 
     if (cli.args.json === true) {
-        console.log(
-            JSON.stringify(
-                {
-                    summary: {
-                        errors: errors.length,
-                        warnings: warnings.length,
-                        strictFailed: cli.args.strict === true && manifest.diagnostics.length > 0,
-                    },
-                    diagnostics: manifest.diagnostics,
-                },
-                null,
-                2,
-            ),
-        );
-    } else if (manifest.diagnostics.length === 0) {
-        console.log('Proteum doctor\n- No manifest diagnostics were found.');
+        console.log(JSON.stringify(response, null, 2));
     } else {
-        console.log(
-            [
-                'Proteum doctor',
-                `- ${errors.length} errors`,
-                `- ${warnings.length} warnings`,
-                '',
-                renderGroup(manifest, errors, 'Errors'),
-                '',
-                renderGroup(manifest, warnings, 'Warnings'),
-            ].join('\n'),
-        );
+        console.log(renderDoctorHuman(manifest, cli.args.strict === true));
     }
 
     if (cli.args.strict === true && manifest.diagnostics.length > 0) {
-        throw new Error(`Proteum doctor failed in strict mode with ${errors.length} errors and ${warnings.length} warnings.`);
+        throw new Error(
+            `Proteum doctor failed in strict mode with ${response.summary.errors} errors and ${response.summary.warnings} warnings.`,
+        );
     }
 };

package/cli/commands/explain.ts

@@ -1,22 +1,15 @@
-import path from 'path';
-
 import cli from '..';
 import Compiler from '../compiler';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
 import {
-    readProteumManifest,
-    type TProteumManifestDiagnostic,
-    type TProteumManifest,
-    type TProteumManifestController,
-    type TProteumManifestLayout,
-    type TProteumManifestRoute,
-    type TProteumManifestService,
-} from '../compiler/common/proteumManifest';
+    explainSectionNames,
+    pickExplainManifestSections,
+    renderExplainHuman,
+    type TExplainSectionName,
+} from '@common/dev/diagnostics';
 
-const explainSectionNames = ['app', 'conventions', 'env', 'services', 'controllers', 'routes', 'layouts', 'diagnostics'] as const;
 const allowedExplainArgs = new Set(['json', 'all', ...explainSectionNames]);
 
-type TExplainSectionName = (typeof explainSectionNames)[number];
-
 const validateExplainArgs = () => {
     const enabledArgs = Object.entries(cli.args)
         .filter(([name, value]) => name !== 'workdir' && name !== 'verbose' && value === true)
@@ -37,185 +30,6 @@ const getSelectedSections = (): TExplainSectionName[] => {
     return explainSectionNames.filter((sectionName) => cli.args[sectionName] === true);
 };
 
-const pickManifestSections = (manifest: TProteumManifest, sectionNames: TExplainSectionName[]) => {
-    if (sectionNames.length === 0) return manifest;
-
-    const selected: Record<string, unknown> = {};
-
-    for (const sectionName of sectionNames) {
-        selected[sectionName] = manifest[sectionName];
-    }
-
-    return selected;
-};
-
-const normalizePath = (value: string) => value.replace(/\\/g, '/');
-const formatLocation = (line?: number, column?: number) =>
-    line && column ? `:${line}:${column}` : line ? `:${line}` : '';
-
-const formatFilepath = (manifest: TProteumManifest, filepath: string) => {
-    const normalizedFilepath = normalizePath(filepath);
-    const normalizedAppRoot = normalizePath(manifest.app.root);
-    const normalizedCoreRoot = normalizePath(manifest.app.coreRoot);
-
-    if (normalizedFilepath === normalizedAppRoot) return '.';
-    if (normalizedFilepath.startsWith(normalizedAppRoot + '/'))
-        return normalizePath(path.relative(normalizedAppRoot, normalizedFilepath)) || '.';
-
-    if (normalizedFilepath === normalizedCoreRoot) return 'node_modules/proteum';
-    if (normalizedFilepath.startsWith(normalizedCoreRoot + '/'))
-        return normalizePath(path.join('node_modules/proteum', path.relative(normalizedCoreRoot, normalizedFilepath)));
-
-    return normalizedFilepath;
-};
-
-const formatService = (manifest: TProteumManifest, service: TProteumManifestService) => {
-    if (service.kind === 'ref') {
-        return `- ${service.registeredName} -> ref ${service.refTo} [${service.parent}]`;
-    }
-
-    const source = service.metasFilepath ? formatFilepath(manifest, service.metasFilepath) : 'unknown';
-    return `- ${service.registeredName} -> ${service.id} (${service.metaName}) [${service.scope}] priority=${service.priority} source=${source}`;
-};
-
-const formatController = (manifest: TProteumManifest, controller: TProteumManifestController) =>
-    `- ${controller.clientAccessor} -> POST ${controller.httpPath} [${controller.scope}] input=${controller.hasInput ? 'yes' : 'no'} source=${formatFilepath(manifest, controller.filepath)}${formatLocation(controller.sourceLocation.line, controller.sourceLocation.column)}#${controller.methodName}`;
-
-const formatRouteTarget = (route: TProteumManifestRoute) => {
-    if (route.kind === 'client-error') return route.code !== undefined ? String(route.code) : route.codeRaw || '?';
-    return route.path || route.pathRaw || '?';
-};
-
-const formatRoute = (manifest: TProteumManifest, route: TProteumManifestRoute) => {
-    const chunk = route.chunkId ? ` chunk=${route.chunkId}` : '';
-    const setup = route.hasSetup ? ' setup=yes' : ' setup=no';
-    const options = route.normalizedOptionKeys.length > 0 ? ` options=${route.normalizedOptionKeys.join(',')}` : '';
-    const resolution = route.targetResolution !== 'literal' ? ` resolution=${route.targetResolution}` : '';
-
-    return `- ${route.kind} ${route.methodName} ${formatRouteTarget(route)} [${route.scope}]${chunk}${setup}${options}${resolution} source=${formatFilepath(manifest, route.filepath)}${formatLocation(route.sourceLocation.line, route.sourceLocation.column)}`;
-};
-
-const formatLayout = (manifest: TProteumManifest, layout: TProteumManifestLayout) =>
-    `- ${layout.chunkId || 'root'} depth=${layout.depth} [${layout.scope}] source=${formatFilepath(manifest, layout.filepath)}`;
-
-const formatDiagnostic = (manifest: TProteumManifest, diagnostic: TProteumManifestDiagnostic) => {
-    const related =
-        diagnostic.relatedFilepaths && diagnostic.relatedFilepaths.length > 0
-            ? ` related=${diagnostic.relatedFilepaths.map((filepath) => formatFilepath(manifest, filepath)).join(',')}`
-            : '';
-
-    return `- [${diagnostic.level}] ${diagnostic.code} ${diagnostic.message} source=${formatFilepath(manifest, diagnostic.filepath)}${formatLocation(diagnostic.sourceLocation?.line, diagnostic.sourceLocation?.column)}${related}`;
-};
-
-const printSection = (title: string, lines: string[]) => {
-    if (lines.length === 0) return `${title}\n- none`;
-    return `${title}\n${lines.join('\n')}`;
-};
-
-const renderSummary = (manifest: TProteumManifest) => {
-    const errorsCount = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
-    const warningsCount = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
-    const providedRequiredEnvVariables = manifest.env.requiredVariables.filter((variable) => variable.provided).length;
-    const lines = [
-        `Proteum manifest: ${formatFilepath(manifest, path.join(manifest.app.root, '.proteum', 'manifest.json'))}`,
-        `App: ${manifest.app.identity.name} (${manifest.app.identity.identifier})`,
-        `Env vars: ${providedRequiredEnvVariables}/${manifest.env.requiredVariables.length} required provided`,
-        `Services: ${manifest.services.app.length} app, ${manifest.services.routerPlugins.length} router plugins`,
-        `Controllers: ${manifest.controllers.length}`,
-        `Routes: ${manifest.routes.client.length} client, ${manifest.routes.server.length} server`,
-        `Layouts: ${manifest.layouts.length}`,
-        `Diagnostics: ${errorsCount} errors, ${warningsCount} warnings`,
-        'Use `proteum explain --json` for the full machine-readable manifest or pass section flags like `routes` and `services`.',
-    ];
-
-    return lines.join('\n');
-};
-
-const renderHuman = (manifest: TProteumManifest, sectionNames: TExplainSectionName[]) => {
-    if (sectionNames.length === 0) return renderSummary(manifest);
-
-    const sections: string[] = [];
-
-    for (const sectionName of sectionNames) {
-        if (sectionName === 'app') {
-            sections.push(
-                printSection('App', [
-                    `- root=${formatFilepath(manifest, manifest.app.root)}`,
-                    `- coreRoot=${formatFilepath(manifest, manifest.app.coreRoot)}`,
-                    `- identity=${formatFilepath(manifest, manifest.app.identityFilepath)}`,
-                    `- name=${manifest.app.identity.name}`,
-                    `- identifier=${manifest.app.identity.identifier}`,
-                    `- title=${manifest.app.identity.fullTitle || manifest.app.identity.title || manifest.app.identity.name}`,
-                ]),
-            );
-            continue;
-        }
-
-        if (sectionName === 'conventions') {
-            sections.push(
-                printSection('Conventions', [
-                    `- routeSetupOptionKeys=${manifest.conventions.routeSetupOptionKeys.join(', ')}`,
-                    `- reservedRouteSetupKeys=${manifest.conventions.reservedRouteSetupKeys.join(', ')}`,
-                ]),
-            );
-            continue;
-        }
-
-        if (sectionName === 'env') {
-            sections.push(
-                printSection('Env', [
-                    `- source=${manifest.env.source}`,
-                    `- loadedVariableKeys=${manifest.env.loadedVariableKeys.join(', ') || 'none'}`,
-                    ...manifest.env.requiredVariables.map(
-                        (variable) =>
-                            `- ${variable.key} possibleValues=${variable.possibleValues.join(' | ')} provided=${variable.provided ? 'yes' : 'no'}`,
-                    ),
-                    `- resolved.name=${manifest.env.resolved.name}`,
-                    `- resolved.profile=${manifest.env.resolved.profile}`,
-                    `- resolved.routerPort=${manifest.env.resolved.routerPort}`,
-                    `- resolved.routerCurrentDomain=${manifest.env.resolved.routerCurrentDomain}`,
-                ]),
-            );
-            continue;
-        }
-
-        if (sectionName === 'services') {
-            sections.push(
-                printSection('App Services', manifest.services.app.map((service) => formatService(manifest, service))),
-                printSection(
-                    'Router Plugins',
-                    manifest.services.routerPlugins.map((service) => formatService(manifest, service)),
-                ),
-            );
-            continue;
-        }
-
-        if (sectionName === 'controllers') {
-            sections.push(printSection('Controllers', manifest.controllers.map((controller) => formatController(manifest, controller))));
-            continue;
-        }
-
-        if (sectionName === 'routes') {
-            sections.push(
-                printSection('Client Routes', manifest.routes.client.map((route) => formatRoute(manifest, route))),
-                printSection('Server Routes', manifest.routes.server.map((route) => formatRoute(manifest, route))),
-            );
-            continue;
-        }
-
-        if (sectionName === 'layouts') {
-            sections.push(printSection('Layouts', manifest.layouts.map((layout) => formatLayout(manifest, layout))));
-            continue;
-        }
-
-        if (sectionName === 'diagnostics') {
-            sections.push(printSection('Diagnostics', manifest.diagnostics.map((diagnostic) => formatDiagnostic(manifest, diagnostic))));
-        }
-    }
-
-    return sections.join('\n\n');
-};
-
 export const run = async (): Promise<void> => {
     validateExplainArgs();
 
@@ -226,9 +40,9 @@ export const run = async (): Promise<void> => {
     const selectedSections = getSelectedSections();
 
     if (cli.args.json === true) {
-        console.log(JSON.stringify(pickManifestSections(manifest, selectedSections), null, 2));
+        console.log(JSON.stringify(pickExplainManifestSections(manifest, selectedSections), null, 2));
         return;
     }
 
-    console.log(renderHuman(manifest, selectedSections));
+    console.log(renderExplainHuman(manifest, selectedSections));
 };

package/cli/commands/trace.ts

@@ -118,6 +118,7 @@ const renderTraceSummary = (request: TRequestTraceListItem) =>
         `status=${request.statusCode ?? 'pending'}`,
         `capture=${request.capture}`,
         `events=${request.eventCount}`,
+        `calls=${request.callCount}`,
         request.user ? `user=${request.user}` : '',
         request.errorMessage ? `error=${request.errorMessage}` : '',
     ]
@@ -131,6 +132,13 @@ const renderTrace = (request: TRequestTrace) =>
         `- started=${request.startedAt} durationMs=${request.durationMs ?? 'pending'} events=${request.events.length} dropped=${request.droppedEvents}`,
         ...(request.user ? [`- user=${request.user}`] : []),
         ...(request.persistedFilepath ? [`- persisted=${request.persistedFilepath}`] : []),
+        'Calls',
+        ...(request.calls.length === 0
+            ? ['- none']
+            : request.calls.map(
+                  (call) =>
+                      `- ${call.origin} ${call.label} ${call.method} ${call.path} status=${call.statusCode ?? 'pending'} durationMs=${call.durationMs ?? 'pending'} req=${call.requestDataKeys.join(',')} res=${call.resultKeys.join(',')}`,
+              )),
         'Events',
         ...request.events.map(
             (event) =>