@chidchanun/bcp 0.1.4 → 0.1.5

package/packages/bundler/src/application-modules.ts

@@ -0,0 +1,771 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    registerHooks,
+} from "node:module";
+import {
+    pathToFileURL,
+} from "node:url";
+
+import type {
+    Plugin,
+} from "esbuild";
+
+export type HydrationMode =
+    | "full"
+    | "none";
+
+const APPLICATION_ALIAS_PREFIX =
+    "@/";
+
+const MODULE_EXTENSIONS = [
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".json",
+] as const;
+
+const CLIENT_REACT_HOOKS = [
+    "useActionState",
+    "useCallback",
+    "useContext",
+    "useDebugValue",
+    "useDeferredValue",
+    "useEffect",
+    "useId",
+    "useImperativeHandle",
+    "useInsertionEffect",
+    "useLayoutEffect",
+    "useMemo",
+    "useOptimistic",
+    "useReducer",
+    "useRef",
+    "useState",
+    "useSyncExternalStore",
+    "useTransition",
+] as const;
+
+let runtimeAliasRoot:
+    string | null =
+    null;
+
+export function installApplicationModuleAlias(
+    rootDirectory: string
+): void {
+    const root =
+        path.resolve(
+            rootDirectory
+        );
+
+    if (runtimeAliasRoot) {
+        if (
+            normalizePath(
+                runtimeAliasRoot
+            ) !==
+            normalizePath(
+                root
+            )
+        ) {
+            throw new Error(
+                `BCP Framework: application alias is already registered for "${runtimeAliasRoot}".`
+            );
+        }
+
+        return;
+    }
+
+    registerHooks({
+        resolve(
+            specifier,
+            context,
+            nextResolve
+        ) {
+            if (
+                !specifier.startsWith(
+                    APPLICATION_ALIAS_PREFIX
+                )
+            ) {
+                return nextResolve(
+                    specifier,
+                    context
+                );
+            }
+
+            const resolved =
+                resolveApplicationModuleAlias(
+                    root,
+                    specifier
+                );
+
+            return nextResolve(
+                pathToFileURL(
+                    resolved
+                ).href,
+                context
+            );
+        },
+    });
+
+    runtimeAliasRoot =
+        root;
+}
+
+export function resolveApplicationModuleAlias(
+    rootDirectory: string,
+    specifier: string
+): string {
+    if (
+        !specifier.startsWith(
+            APPLICATION_ALIAS_PREFIX
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: application alias must start with "${APPLICATION_ALIAS_PREFIX}".`
+        );
+    }
+
+    const aliasPath =
+        specifier.slice(
+            APPLICATION_ALIAS_PREFIX.length
+        );
+
+    if (
+        !aliasPath ||
+        aliasPath.includes("\\")
+    ) {
+        throw new Error(
+            `BCP Framework: invalid application alias "${specifier}".`
+        );
+    }
+
+    const root =
+        path.resolve(
+            rootDirectory
+        );
+
+    const unresolvedPath =
+        path.resolve(
+            root,
+            aliasPath.replaceAll(
+                "/",
+                path.sep
+            )
+        );
+
+    if (
+        !isPathInside(
+            root,
+            unresolvedPath
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: application alias "${specifier}" cannot resolve outside the project root.`
+        );
+    }
+
+    const resolvedPath =
+        resolveExistingModulePath(
+            unresolvedPath
+        );
+
+    if (!resolvedPath) {
+        throw new Error(
+            `BCP Framework: application alias "${specifier}" could not be resolved from "${root}".`
+        );
+    }
+
+    const realRoot =
+        safeRealPath(
+            root
+        ) ??
+        root;
+    const realResolved =
+        safeRealPath(
+            resolvedPath
+        ) ??
+        resolvedPath;
+
+    if (
+        !isPathInside(
+            realRoot,
+            realResolved
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: application alias "${specifier}" resolved outside the project root through a symbolic link.`
+        );
+    }
+
+    return realResolved;
+}
+
+export function createApplicationAliasPlugin(
+    rootDirectory: string
+): Plugin {
+    return {
+        name:
+            "bcp-application-alias",
+
+        setup(buildApi) {
+            buildApi.onResolve(
+                {
+                    filter:
+                        /^@\//,
+                },
+                (args) => {
+                    try {
+                        return {
+                            path:
+                                resolveApplicationModuleAlias(
+                                    rootDirectory,
+                                    args.path
+                                ),
+                        };
+                    } catch (error) {
+                        return {
+                            errors: [
+                                {
+                                    text:
+                                        error instanceof Error
+                                            ? error.message
+                                            : String(error),
+                                },
+                            ],
+                        };
+                    }
+                }
+            );
+        },
+    };
+}
+
+export function createClientBoundaryPlugin(
+    rootDirectory: string
+): Plugin {
+    const root =
+        path.resolve(
+            rootDirectory
+        );
+
+    return {
+        name:
+            "bcp-client-boundary",
+
+        setup(buildApi) {
+            buildApi.onResolve(
+                {
+                    filter:
+                        /^bcp\/server-only$/,
+                },
+                (args) => {
+                    const importer =
+                        args.importer
+                            ? formatApplicationPath(
+                                root,
+                                args.importer
+                            )
+                            : "the current client entry";
+
+                    return {
+                        errors: [
+                            {
+                                text:
+                                    `BCP Framework: bcp/server-only cannot be imported into a client bundle from ${importer}. Move the server dependency behind an API route or use export const hydration = "none" for a server-only page route.`,
+                            },
+                        ],
+                    };
+                }
+            );
+
+            buildApi.onLoad(
+                {
+                    filter:
+                        /\.[cm]?[jt]sx?$/,
+                },
+                async (args) => {
+                    if (
+                        !isApplicationSourcePath(
+                            root,
+                            args.path
+                        ) ||
+                        /\.island\.(?:ts|tsx)$/.test(
+                            args.path
+                        )
+                    ) {
+                        return;
+                    }
+
+                    const source =
+                        await fs.promises
+                            .readFile(
+                                args.path,
+                                "utf8"
+                            );
+
+                    if (
+                        usesReactClientHooks(
+                            source
+                        ) &&
+                        !hasUseClientDirective(
+                            source
+                        )
+                    ) {
+                        return {
+                            errors: [
+                                {
+                                    text:
+                                        `BCP Framework: ${formatApplicationPath(root, args.path)} uses React client hooks but is missing the "use client" directive. Add "use client" as the first directive in the module.`,
+                                },
+                            ],
+                        };
+                    }
+
+                    return;
+                }
+            );
+        },
+    };
+}
+
+export function readRouteHydrationMode(
+    filePath: string
+): HydrationMode {
+    const source =
+        fs.readFileSync(
+            filePath,
+            "utf8"
+        );
+
+    const match =
+        /\bexport\s+const\s+hydration\s*(?::[^=;]+)?=\s*["']([^"']+)["']/.exec(
+            source
+        );
+
+    if (!match) {
+        return "full";
+    }
+
+    const value =
+        match[1];
+
+    if (
+        value === "full" ||
+        value === "none"
+    ) {
+        return value;
+    }
+
+    throw new Error(
+        `BCP Framework: invalid hydration mode "${value}" in "${filePath}". Use "full" or "none".`
+    );
+}
+
+export function hasUseClientDirective(
+    source: string
+): boolean {
+    let index =
+        source.charCodeAt(0) ===
+            0xfeff
+            ? 1
+            : 0;
+
+    while (
+        index <
+        source.length
+    ) {
+        index =
+            skipTrivia(
+                source,
+                index
+            );
+
+        const remaining =
+            source.slice(
+                index
+            );
+
+        const directive =
+            /^(["'])([^"']+)\1\s*;?/.exec(
+                remaining
+            );
+
+        if (!directive) {
+            return false;
+        }
+
+        if (
+            directive[2] ===
+            "use client"
+        ) {
+            return true;
+        }
+
+        index +=
+            directive[0].length;
+    }
+
+    return false;
+}
+
+export function usesReactClientHooks(
+    source: string
+): boolean {
+    const hookPattern =
+        new RegExp(
+            `\\b(?:${CLIENT_REACT_HOOKS.join("|")})\\b`
+        );
+
+    const importPattern =
+        /\bimport\s+([\s\S]*?)\s+from\s+["']react["']/g;
+
+    let match:
+        RegExpExecArray | null;
+
+    while (
+        (
+            match =
+                importPattern.exec(
+                    source
+                )
+        )
+    ) {
+        const clause =
+            match[1];
+
+        if (
+            hookPattern.test(
+                clause
+            )
+        ) {
+            return true;
+        }
+
+        const namespaceMatch =
+            /\*\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)/.exec(
+                clause
+            );
+
+        const defaultMatch =
+            /^\s*([A-Za-z_$][A-Za-z0-9_$]*)/.exec(
+                clause
+            );
+
+        for (
+            const namespace
+            of [
+                namespaceMatch?.[1],
+                defaultMatch?.[1],
+            ]
+        ) {
+            if (!namespace) {
+                continue;
+            }
+
+            const namespaceHookPattern =
+                new RegExp(
+                    `\\b${escapeRegExp(namespace)}\\s*\\.\\s*(?:${CLIENT_REACT_HOOKS.join("|")})\\s*\\(`
+                );
+
+            if (
+                namespaceHookPattern.test(
+                    source
+                )
+            ) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
+
+function resolveExistingModulePath(
+    unresolvedPath: string
+): string | null {
+    if (
+        isFile(
+            unresolvedPath
+        )
+    ) {
+        return unresolvedPath;
+    }
+
+    if (
+        path.extname(
+            unresolvedPath
+        ) === ""
+    ) {
+        for (
+            const extension
+            of MODULE_EXTENSIONS
+        ) {
+            const candidate =
+                `${unresolvedPath}${extension}`;
+
+            if (
+                isFile(
+                    candidate
+                )
+            ) {
+                return candidate;
+            }
+        }
+    }
+
+    if (
+        isDirectory(
+            unresolvedPath
+        )
+    ) {
+        for (
+            const extension
+            of MODULE_EXTENSIONS
+        ) {
+            const candidate =
+                path.join(
+                    unresolvedPath,
+                    `index${extension}`
+                );
+
+            if (
+                isFile(
+                    candidate
+                )
+            ) {
+                return candidate;
+            }
+        }
+    }
+
+    return null;
+}
+
+function isApplicationSourcePath(
+    rootDirectory: string,
+    filePath: string
+): boolean {
+    const absolute =
+        path.resolve(
+            filePath
+        );
+
+    if (
+        !isPathInside(
+            rootDirectory,
+            absolute
+        )
+    ) {
+        return false;
+    }
+
+    const relative =
+        path.relative(
+            rootDirectory,
+            absolute
+        )
+            .replace(
+                /\\/g,
+                "/"
+            );
+
+    return !(
+        relative ===
+            "node_modules" ||
+        relative.startsWith(
+            "node_modules/"
+        ) ||
+        relative ===
+            ".bcp-framework" ||
+        relative.startsWith(
+            ".bcp-framework/"
+        )
+    );
+}
+
+function skipTrivia(
+    source: string,
+    startIndex: number
+): number {
+    let index =
+        startIndex;
+
+    while (
+        index <
+        source.length
+    ) {
+        const whitespace =
+            /^[\s]+/.exec(
+                source.slice(
+                    index
+                )
+            );
+
+        if (whitespace) {
+            index +=
+                whitespace[0].length;
+            continue;
+        }
+
+        if (
+            source.startsWith(
+                "//",
+                index
+            )
+        ) {
+            const newline =
+                source.indexOf(
+                    "\n",
+                    index + 2
+                );
+
+            return newline === -1
+                ? source.length
+                : skipTrivia(
+                    source,
+                    newline + 1
+                );
+        }
+
+        if (
+            source.startsWith(
+                "/*",
+                index
+            )
+        ) {
+            const end =
+                source.indexOf(
+                    "*/",
+                    index + 2
+                );
+
+            if (end === -1) {
+                return source.length;
+            }
+
+            index =
+                end + 2;
+            continue;
+        }
+
+        break;
+    }
+
+    return index;
+}
+
+function formatApplicationPath(
+    rootDirectory: string,
+    filePath: string
+): string {
+    const relative =
+        path.relative(
+            rootDirectory,
+            filePath
+        )
+            .replace(
+                /\\/g,
+                "/"
+            );
+
+    return relative &&
+        !relative.startsWith(
+            ".."
+        )
+        ? `"${relative}"`
+        : `"${filePath}"`;
+}
+
+function isPathInside(
+    parent: string,
+    child: string
+): boolean {
+    const relative =
+        path.relative(
+            parent,
+            child
+        );
+
+    return (
+        relative === "" ||
+        (
+            relative !== ".." &&
+            !relative.startsWith(
+                `..${path.sep}`
+            ) &&
+            !path.isAbsolute(
+                relative
+            )
+        )
+    );
+}
+
+function safeRealPath(
+    filePath: string
+): string | null {
+    try {
+        return fs.realpathSync(
+            filePath
+        );
+    } catch {
+        return null;
+    }
+}
+
+function isFile(
+    filePath: string
+): boolean {
+    try {
+        return fs.statSync(
+            filePath
+        ).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function isDirectory(
+    filePath: string
+): boolean {
+    try {
+        return fs.statSync(
+            filePath
+        ).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function normalizePath(
+    filePath: string
+): string {
+    let normalized =
+        path.normalize(
+            path.resolve(
+                filePath
+            )
+        );
+
+    if (
+        process.platform ===
+        "win32"
+    ) {
+        normalized =
+            normalized.toLowerCase();
+    }
+
+    return normalized;
+}
+
+function escapeRegExp(
+    value: string
+): string {
+    return value.replace(
+        /[.*+?^${}()|[\]\\]/g,
+        "\\$&"
+    );
+}