@webstir-io/webstir-frontend 0.1.40

package/src/watch/hotUpdateTracker.ts

@@ -0,0 +1,285 @@
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import type { BuildResult, Metafile } from 'esbuild';
+import { FOLDERS, FILES, EXTENSIONS } from '../core/constants.js';
+import { emitDiagnostic } from '../core/diagnostics.js';
+import type { FrontendConfig } from '../types.js';
+import type { BuilderContext } from '../builders/types.js';
+import { pathExists } from '../utils/fs.js';
+import { isPathInside } from '../utils/changedFile.js';
+import { findPageFromChangedFile } from '../utils/pathMatch.js';
+
+export interface HotAsset {
+    readonly type: 'js' | 'css';
+    readonly path: string;
+    readonly relativePath: string;
+    readonly url: string;
+}
+
+export interface HotUpdateDetails {
+    readonly modules: readonly HotAsset[];
+    readonly styles: readonly HotAsset[];
+    readonly requiresReload: boolean;
+    readonly fallbackReasons: readonly string[];
+    readonly changedFile?: string;
+    readonly stats?: HotUpdateStats;
+}
+
+export interface HotUpdateStats {
+    readonly hotUpdates: number;
+    readonly reloadFallbacks: number;
+}
+
+interface ProcessJavaScriptResult {
+    readonly modules: readonly HotAsset[];
+    readonly requiresReload: boolean;
+    readonly fallbackReasons: readonly string[];
+}
+
+interface CollectCssResult {
+    readonly styles: readonly HotAsset[];
+    readonly requiresReload: boolean;
+    readonly fallbackReasons: readonly string[];
+}
+
+interface HotUpdateTrackerOptions {
+    readonly workspaceRoot: string;
+}
+
+export class HotUpdateTracker {
+    private readonly workspaceRoot: string;
+    private readonly pageOutputHashes = new Map<string, Map<string, { hash: string }>>();
+    private readonly assetFingerprints = new Map<string, string>();
+
+    public constructor(options: HotUpdateTrackerOptions) {
+        this.workspaceRoot = options.workspaceRoot;
+    }
+
+    public reset(): void {
+        this.pageOutputHashes.clear();
+        this.assetFingerprints.clear();
+    }
+
+    public removePage(pageName: string): void {
+        this.pageOutputHashes.delete(pageName);
+    }
+
+    public async processJavaScriptResult(
+        pageName: string,
+        result: BuildResult,
+        config: FrontendConfig
+    ): Promise<ProcessJavaScriptResult> {
+        const modules: HotAsset[] = [];
+        let requiresReload = false;
+        const fallbackReasons: string[] = [];
+        const metafile = result.metafile as Metafile | undefined;
+
+        if (!metafile) {
+            fallbackReasons.push('javascript.metafile.missing');
+            return { modules, requiresReload: true, fallbackReasons };
+        }
+
+        const buildRoot = config.paths.build.frontend;
+        const currentOutputs = new Set<string>();
+        const previousOutputs = this.pageOutputHashes.get(pageName) ?? new Map<string, { hash: string }>();
+
+        for (const outputPath of Object.keys(metafile.outputs)) {
+            const extension = path.extname(outputPath).toLowerCase();
+            if (extension !== EXTENSIONS.js && extension !== '.mjs') {
+                continue;
+            }
+
+            const absoluteOutput = this.resolveOutputPath(outputPath);
+            currentOutputs.add(absoluteOutput);
+
+            const fingerprint = await this.computeAssetFingerprint(absoluteOutput, buildRoot, 'js');
+            if (!fingerprint) {
+                if (this.assetFingerprints.has(absoluteOutput)) {
+                    this.assetFingerprints.delete(absoluteOutput);
+                }
+                if (previousOutputs.has(absoluteOutput)) {
+                    previousOutputs.delete(absoluteOutput);
+                    requiresReload = true;
+                    fallbackReasons.push('javascript.output.missing');
+                }
+                continue;
+            }
+
+            if (fingerprint.requiresReload) {
+                requiresReload = true;
+                fallbackReasons.push('javascript.fingerprint.error');
+            }
+
+            if (fingerprint.changed) {
+                modules.push(fingerprint.asset);
+            }
+
+            if (fingerprint.hash) {
+                previousOutputs.set(absoluteOutput, { hash: fingerprint.hash });
+            } else if (previousOutputs.has(absoluteOutput)) {
+                previousOutputs.delete(absoluteOutput);
+            }
+        }
+
+        for (const known of Array.from(previousOutputs.keys())) {
+            if (!currentOutputs.has(known)) {
+                previousOutputs.delete(known);
+                requiresReload = true;
+                fallbackReasons.push('javascript.output.removed');
+            }
+        }
+
+        this.pageOutputHashes.set(pageName, previousOutputs);
+        return { modules, requiresReload, fallbackReasons: uniqueReasons(fallbackReasons) };
+    }
+
+    public async collectCssChanges(
+        context: BuilderContext,
+        pageNames: readonly string[]
+    ): Promise<CollectCssResult> {
+        const { config, changedFile } = context;
+        const buildRoot = config.paths.build.frontend;
+        const candidates = new Set<string>();
+
+        if (!changedFile) {
+            for (const page of pageNames) {
+                candidates.add(this.getPageCssOutputPath(config, page));
+            }
+            candidates.add(this.getAppCssOutputPath(config));
+        } else {
+            const normalized = path.resolve(changedFile);
+            const extension = path.extname(normalized).toLowerCase();
+            if (extension === EXTENSIONS.css) {
+                if (isPathInside(normalized, config.paths.src.app)) {
+                    for (const page of pageNames) {
+                        candidates.add(this.getPageCssOutputPath(config, page));
+                    }
+                    candidates.add(this.getAppCssOutputPath(config));
+                } else if (isPathInside(normalized, config.paths.src.pages)) {
+                    const page = findPageFromChangedFile(normalized, config.paths.src.pages);
+                    if (page) {
+                        candidates.add(this.getPageCssOutputPath(config, page));
+                    }
+                } else if (isPathInside(normalized, config.paths.src.frontend)) {
+                    for (const page of pageNames) {
+                        candidates.add(this.getPageCssOutputPath(config, page));
+                    }
+                    candidates.add(this.getAppCssOutputPath(config));
+                }
+            }
+        }
+
+        if (candidates.size === 0 && !changedFile) {
+            candidates.add(this.getAppCssOutputPath(config));
+            for (const page of pageNames) {
+                candidates.add(this.getPageCssOutputPath(config, page));
+            }
+        }
+
+        const styles: HotAsset[] = [];
+        let requiresReload = !changedFile;
+        const fallbackReasons: string[] = [];
+
+        if (!changedFile) {
+            fallbackReasons.push('css.full-rebuild');
+        }
+
+        for (const candidate of candidates) {
+            const fingerprint = await this.computeAssetFingerprint(candidate, buildRoot, 'css');
+            if (!fingerprint) {
+                if (this.assetFingerprints.has(path.resolve(candidate))) {
+                    this.assetFingerprints.delete(path.resolve(candidate));
+                    requiresReload = true;
+                    fallbackReasons.push('css.asset.missing');
+                }
+                continue;
+            }
+
+            if (fingerprint.requiresReload) {
+                requiresReload = true;
+                fallbackReasons.push('css.fingerprint.error');
+            }
+
+            if (fingerprint.changed) {
+                styles.push(fingerprint.asset);
+            }
+        }
+
+        return { styles, requiresReload, fallbackReasons: uniqueReasons(fallbackReasons) };
+    }
+
+    private async computeAssetFingerprint(
+        filePath: string,
+        buildRoot: string,
+        type: HotAsset['type']
+    ): Promise<{ asset: HotAsset; changed: boolean; requiresReload: boolean; hash?: string } | null> {
+        const absolutePath = path.resolve(filePath);
+        if (!(await pathExists(absolutePath))) {
+            return null;
+        }
+
+        try {
+            const contents = await readFile(absolutePath);
+            const hash = createHash('sha1').update(contents).digest('hex');
+            const previous = this.assetFingerprints.get(absolutePath);
+            const changed = previous !== hash;
+            this.assetFingerprints.set(absolutePath, hash);
+            return {
+                asset: this.createHotAsset(absolutePath, buildRoot, type),
+                changed,
+                requiresReload: false,
+                hash
+            };
+        } catch (error) {
+            emitDiagnostic({
+                code: 'frontend.watch.unexpected',
+                kind: 'watch-daemon',
+                stage: 'css-fingerprint',
+                severity: 'error',
+                message: `Failed to fingerprint asset '${absolutePath}': ${error instanceof Error ? error.message : String(error)}`
+            });
+
+            return {
+                asset: this.createHotAsset(absolutePath, buildRoot, type),
+                changed: false,
+                requiresReload: true
+            };
+        }
+    }
+
+    private getPageCssOutputPath(config: FrontendConfig, pageName: string): string {
+        return path.join(config.paths.build.frontend, FOLDERS.pages, pageName, `${FILES.index}${EXTENSIONS.css}`);
+    }
+
+    private getAppCssOutputPath(config: FrontendConfig): string {
+        return path.join(config.paths.build.frontend, FOLDERS.app, 'app.css');
+    }
+
+    private createHotAsset(filePath: string, buildRoot: string, type: HotAsset['type']): HotAsset {
+        const relativePath = path.relative(buildRoot, filePath);
+        const webPath = this.toWebPath(relativePath);
+        return {
+            type,
+            path: filePath,
+            relativePath,
+            url: webPath.startsWith('/') ? webPath : `/${webPath}`
+        };
+    }
+
+    private resolveOutputPath(outputPath: string): string {
+        if (path.isAbsolute(outputPath)) {
+            return outputPath;
+        }
+
+        return path.resolve(this.workspaceRoot, outputPath);
+    }
+
+    private toWebPath(relativePath: string): string {
+        return relativePath.split(path.sep).join('/') || '';
+    }
+}
+
+function uniqueReasons(reasons: readonly string[]): readonly string[] {
+    return Array.from(new Set(reasons.filter(Boolean)));
+}

package/src/watch/pipelineHelpers.ts

@@ -0,0 +1,242 @@
+import type { BuildFailure, Message } from 'esbuild';
+import { emitDiagnostic } from '../core/diagnostics.js';
+import type { DiagnosticSeverity } from '../core/diagnostics.js';
+import type { Builder, BuilderContext } from '../builders/types.js';
+import { WatchReporter, serializeMessages, type SerializedMessage } from './watchReporter.js';
+import type { HotAsset, HotUpdateDetails } from './hotUpdateTracker.js';
+
+const BUILDER_DISPLAY_NAMES: Record<string, string> = {
+    css: 'CSS',
+    html: 'HTML',
+    'static-assets': 'Static assets'
+} as const;
+
+export interface JavaScriptBuildSummary {
+    readonly pagesBuilt: readonly string[];
+    readonly warnings: readonly SerializedMessage[];
+    readonly modules: readonly HotAsset[];
+    readonly requiresReload: boolean;
+    readonly fallbackReasons: readonly string[];
+}
+
+export interface AdditionalBuildResult {
+    readonly succeeded: boolean;
+    readonly assets: readonly string[];
+    readonly styles: readonly HotAsset[];
+    readonly requiresReload: boolean;
+    readonly fallbackReasons: readonly string[];
+}
+
+export async function runBuilderWithDiagnostics(
+    builder: Builder,
+    reporter: WatchReporter,
+    context: BuilderContext,
+    changedFile: string | undefined,
+    relativeChange: string | undefined
+): Promise<boolean> {
+    const displayName = BUILDER_DISPLAY_NAMES[builder.name] ?? builder.name;
+    const messageContext = relativeChange ? ` (${relativeChange})` : '';
+
+    reporter.emitVerbose({
+        code: `frontend.watch.${builder.name}.build.start`,
+        kind: 'watch-daemon',
+        stage: builder.name,
+        severity: 'info',
+        message: `Starting ${displayName} rebuild${messageContext}.`,
+        data: changedFile ? { changedFile, builder: builder.name } : { builder: builder.name }
+    });
+
+    try {
+        await builder.build(context);
+        reporter.emitVerbose({
+            code: `frontend.watch.${builder.name}.build.success`,
+            kind: 'watch-daemon',
+            stage: builder.name,
+            severity: 'info',
+            message: `${displayName} rebuild completed${messageContext}.`,
+            data: changedFile ? { changedFile, builder: builder.name } : { builder: builder.name }
+        });
+        return true;
+    } catch (error) {
+        const details: Record<string, unknown> = { builder: builder.name };
+        if (changedFile) {
+            details.changedFile = changedFile;
+        }
+        if (error instanceof Error) {
+            details.error = error.message;
+        } else {
+            details.error = String(error);
+        }
+
+        emitDiagnostic({
+            code: `frontend.watch.${builder.name}.build.failure`,
+            kind: 'watch-daemon',
+            stage: builder.name,
+            severity: 'error',
+            message: `${displayName} rebuild failed${messageContext}.`,
+            data: details
+        });
+
+        return false;
+    }
+}
+
+export function emitPipelineSuccess(
+    summary: JavaScriptBuildSummary,
+    assetsResult: AdditionalBuildResult,
+    changedFile: string | undefined,
+    relativeChange: string | undefined,
+    hotUpdate: HotUpdateDetails
+): void {
+    const message = `Frontend rebuild pipeline completed${relativeChange ? ` (${relativeChange})` : ''}.`;
+
+    const data: Record<string, unknown> = {
+        pages: summary.pagesBuilt,
+        assets: assetsResult.assets,
+        hotUpdate: serializeHotUpdate(hotUpdate, relativeChange)
+    };
+
+    if (relativeChange) {
+        data.changedFile = relativeChange;
+    } else if (changedFile) {
+        data.changedFile = changedFile;
+    }
+
+    if (summary.warnings.length > 0) {
+        data.javascriptWarnings = summary.warnings;
+    }
+
+    emitDiagnostic({
+        code: 'frontend.watch.pipeline.success',
+        kind: 'watch-daemon',
+        stage: 'pipeline',
+        severity: 'info',
+        message,
+        data
+    });
+}
+
+export function serializeSummary(
+    summary: JavaScriptBuildSummary,
+    changedFile: string | undefined,
+    skipped: boolean
+): Record<string, unknown> {
+    const data: Record<string, unknown> = {
+        pages: summary.pagesBuilt
+    };
+
+    if (changedFile) {
+        data.changedFile = changedFile;
+    }
+
+    if (summary.warnings.length > 0) {
+        data.warnings = summary.warnings;
+    }
+
+    if (skipped) {
+        data.skipped = true;
+    }
+
+    if (summary.modules.length > 0) {
+        data.modules = summary.modules.map(asset => asset.url);
+    }
+
+    if (summary.requiresReload) {
+        data.requiresReload = true;
+    }
+
+    if (summary.fallbackReasons.length > 0) {
+        data.fallbackReasons = summary.fallbackReasons;
+    }
+
+    return data;
+}
+
+export function emitJavaScriptFailure(error: unknown, changedFile?: string): void {
+    let message = 'JavaScript rebuild failed.';
+    let severity: DiagnosticSeverity = 'error';
+    const data: Record<string, unknown> = changedFile ? { changedFile } : {};
+
+    if (error instanceof JavaScriptBuildError) {
+        message = `JavaScript rebuild failed for page '${error.pageName}'.`;
+        if (error.details.length > 0) {
+            data.errors = error.details;
+        }
+    } else if (error instanceof Error) {
+        message = `JavaScript rebuild failed: ${error.message}`;
+    }
+
+    emitDiagnostic({
+        code: 'frontend.watch.javascript.build.failure',
+        kind: 'watch-daemon',
+        stage: 'javascript',
+        severity,
+        message,
+        data: Object.keys(data).length > 0 ? data : undefined
+    });
+}
+
+export class JavaScriptBuildError extends Error {
+    public readonly pageName: string;
+    public readonly details: readonly SerializedMessage[];
+
+    public constructor(pageName: string, cause: unknown) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(message);
+        this.pageName = pageName;
+        this.details = isBuildFailure(cause) ? serializeMessages(cause.errors ?? []) : [];
+    }
+}
+
+function serializeHotUpdate(hotUpdate: HotUpdateDetails, relativeChange?: string): Record<string, unknown> {
+    const data: Record<string, unknown> = {
+        requiresReload: hotUpdate.requiresReload,
+        modules: hotUpdate.modules.map(asset => serializeHotAsset(asset)),
+        styles: hotUpdate.styles.map(asset => serializeHotAsset(asset))
+    };
+
+    if (relativeChange) {
+        data.changedFile = relativeChange;
+    } else if (hotUpdate.changedFile) {
+        data.changedFile = hotUpdate.changedFile;
+    }
+
+    if (hotUpdate.fallbackReasons.length > 0) {
+        data.fallbackReasons = hotUpdate.fallbackReasons;
+    }
+
+    if (hotUpdate.stats) {
+        data.stats = {
+            hotUpdates: hotUpdate.stats.hotUpdates,
+            reloadFallbacks: hotUpdate.stats.reloadFallbacks
+        };
+    }
+
+    return data;
+}
+
+function serializeHotAsset(asset: HotAsset): Record<string, string> {
+    return {
+        type: asset.type,
+        path: asset.path,
+        relativePath: asset.relativePath,
+        url: asset.url
+    };
+}
+
+function isBuildFailure(error: unknown): error is BuildFailure {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+
+    const candidate = error as BuildFailure;
+    return Array.isArray(candidate.errors) && candidate.errors.every(isEsbuildMessage);
+}
+
+function isEsbuildMessage(candidate: unknown): candidate is Message {
+    if (typeof candidate !== 'object' || candidate === null) {
+        return false;
+    }
+
+    return typeof (candidate as Message).text === 'string';
+}

package/src/watch/types.ts

@@ -0,0 +1,23 @@
+export type WatchDaemonCommand =
+    | { readonly type: 'start' }
+    | { readonly type: 'change'; readonly path: string }
+    | { readonly type: 'reload' }
+    | { readonly type: 'shutdown' }
+    | { readonly type: 'ping'; readonly id?: string };
+
+export interface WatchDaemonOptions {
+    readonly workspaceRoot: string;
+    readonly autoStart?: boolean;
+    readonly verbose?: boolean;
+    readonly hmrVerbose?: boolean;
+}
+
+export interface WatchCoordinatorOptions {
+    readonly workspaceRoot: string;
+    readonly verbose?: boolean;
+    readonly hmrVerbose?: boolean;
+}
+
+export interface WatchChangeIntent {
+    readonly path?: string;
+}