@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/client-script-bundler.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Client Script Bundler
+ *
+ * Uses Bun.build to resolve and bundle imports in `<script client>` blocks.
+ * Only activates when real user imports are detected (local files, npm packages).
+ * stx runtime, @stores, and @composables are marked as external — handled
+ * by existing auto-import and store-import transforms.
+ *
+ * @module client-script-bundler
+ */
+import type { BuildFailureDetail } from './build-message';
+export declare function clientBundleDependencies(filePath: string): string[];
+export declare function shouldLogBundlerDiagnostics(environment?: {
+    STX_DEBUG?: string;
+}): boolean;
+/**
+ * Client-script bundle failures recorded during the current process.
+ *
+ * When a `<script client>` block fails to bundle, the bundler falls back to
+ * shipping the ORIGINAL, unbundled source so the page still renders. That is a
+ * reasonable dev-server behaviour and a terrible build behaviour: imports never
+ * resolve, bindings silently do nothing, and `stx build` still exited 0, so CI
+ * published a broken page as a success.
+ *
+ * Nothing was counting these. `ssg.failedCount` only ever saw render-time throws,
+ * never a bundle failure, because the fallback swallowed it and returned a
+ * string. The registry gives the build a way to ask, without the bundler having
+ * to know whether it is running under a dev server or a build. See #1884.
+ */
+export interface BundleFailure {
+    filePath: string;
+    message: string;
+    /**
+     * The same failure with its position intact, for a dev-server overlay to
+     * draw a code frame from. Absent only when the thrower gave no position.
+     */
+    details?: BuildFailureDetail[];
+}
+/** Record a bundle failure. Called from the bundler's fallback path. */
+export declare function recordBundleFailure(filePath: string, message: string, details?: BuildFailureDetail[]): void;
+/** Every bundle failure since the last reset. */
+export declare function getBundleFailures(): BundleFailure[];
+/** Drop recorded failures — call at the start of a build, and in tests. */
+export declare function clearBundleFailures(): void;
+/** What to do when a client script will not bundle. */
+export type BundlerFallbackMode = 'warn' | 'error';
+/**
+ * Override the configured fallback mode, for tests and embedders.
+ *
+ * Pass `undefined` to go back to reading `strict.bundlerFallback` from config.
+ */
+export declare function setBundlerFallbackMode(mode: BundlerFallbackMode | undefined): void;
+/**
+ * The effective fallback mode.
+ *
+ * Read lazily rather than captured at import time: config is loaded after this
+ * module is first imported, so a value read at import time is always the
+ * default.
+ */
+export declare function resolveBundlerFallback(): BundlerFallbackMode;
+/**
+ * Check if a script has user imports that need Bun.build bundling.
+ *
+ * Returns false for:
+ * - `import type { ... }` (type-only — stripped by TS transpiler)
+ * - `import { ... } from 'stx'` (auto-imported from window.stx)
+ * - `import '@stacksjs/browser'` (the framework-injected module bootstrap)
+ * - `import { ... } from '@stores'` (handled by transformStoreImports)
+ * - `import { ... } from '@composables'` (handled by transformStoreImports)
+ */
+export declare function hasUserImports(code: string): boolean;
+/**
+ * Run one client bundle build at a time.
+ *
+ * Bun.build can return transient "Unseekable reading file" failures when
+ * separate builds concurrently traverse the same linked workspace dependency.
+ * Dashboard renders commonly compile the layout and page controllers together,
+ * so distinct content hashes still share much of their dependency graph.
+ *
+ * Cache reads remain concurrent and identical builds still share one promise.
+ * Only cold Bun.build work is queued, and a rejected task cannot stall the next
+ * build.
+ */
+export declare function queueClientBundleBuild<T>(task: () => Promise<T>): Promise<T>;
+export declare function bundleClientScript(code: string, filePath: string, options?: {
+    projectRoot?: string;
+    minify?: boolean;
+    cacheDir?: string;
+    /**
+     * Receives the files this bundle was built from, for a caller that needs
+     * them for its own cache key.
+     *
+     * `clientBundleDependencies()` answers the same question from a map keyed
+     * by host file path, which is only correct while calls for one host are
+     * serialized. They are not: a component with two bundling `<script client>`
+     * blocks builds them under one `Promise.all`, so the second call's
+     * `recordBundleInputs` can land between the first's await and its read, and
+     * the first caller gets the second's file list. That map is a
+     * process-global keyed on the host, so it cannot distinguish them; this
+     * hands each caller its own answer.
+     */
+    collectInputs?: string[];
+}): Promise<string>;

package/dist/client-script-bundler.js

@@ -0,0 +1,390 @@
+import "./bun-shim.js"
+import path from "node:path";
+import fs from "node:fs";
+import { getPublicEnvDefine } from "./public-env.js";
+import { stateDir } from "./state-dir.js";
+import { describeBuildFailure, formatBuildFailure } from "./build-message.js";
+import { config } from "./config.js";
+import { depsUnchanged, renderMemo } from "./render-memo.js";
+const BUNDLE_CACHE_VERSION = 5, BUNDLE_CACHE_METADATA_VERSION = 1, bundleInputs = new Map, CACHE_ENTRY_LIMIT = 600, SWEEP_EVERY = 100, writesSinceSweep = new Map;
+async function pruneBundleCache(cacheDir) {
+  const since = writesSinceSweep.get(cacheDir) ?? 0;
+  if (since > 0 && since < SWEEP_EVERY) {
+    writesSinceSweep.set(cacheDir, since + 1);
+    return;
+  }
+  writesSinceSweep.set(cacheDir, 1);
+  try {
+    const names = (await fs.promises.readdir(cacheDir)).filter((name) => name.endsWith(".js"));
+    if (names.length <= CACHE_ENTRY_LIMIT)
+      return;
+    const alive = (await Promise.all(names.map(async (name) => {
+      try {
+        return { name, at: (await fs.promises.stat(path.join(cacheDir, name))).mtimeMs };
+      } catch {
+        return null;
+      }
+    }))).filter((entry) => entry !== null);
+    alive.sort((a, b) => b.at - a.at);
+    for (const entry of alive.slice(CACHE_ENTRY_LIMIT)) {
+      const base = entry.name.slice(0, -3);
+      await fs.promises.rm(path.join(cacheDir, `${base}.js`), { force: !0 });
+      await fs.promises.rm(path.join(cacheDir, `${base}.deps.json`), { force: !0 });
+    }
+    logBundlerDiagnostic("pruned bundle cache to", CACHE_ENTRY_LIMIT, "entries");
+  } catch {}
+}
+export function clientBundleDependencies(filePath) {
+  return bundleInputs.get(filePath) ?? [];
+}
+function recordBundleInputs(filePath, files) {
+  if (filePath)
+    bundleInputs.set(filePath, files);
+}
+export function shouldLogBundlerDiagnostics(environment = process.env) {
+  return environment.STX_DEBUG === "true" || environment.STX_DEBUG === "1";
+}
+function logBundlerDiagnostic(...message) {
+  if (shouldLogBundlerDiagnostics())
+    console.log("[stx:bundler]", ...message);
+}
+const _bundleFailures = [];
+export function recordBundleFailure(filePath, message, details) {
+  _bundleFailures.push({ filePath: filePath || "<inline>", message, details });
+}
+export function getBundleFailures() {
+  return _bundleFailures.slice();
+}
+export function clearBundleFailures() {
+  _bundleFailures.length = 0;
+}
+let _fallbackOverride;
+export function setBundlerFallbackMode(mode) {
+  _fallbackOverride = mode;
+}
+export function resolveBundlerFallback() {
+  if (_fallbackOverride)
+    return _fallbackOverride;
+  try {
+    const strict = config.strict;
+    return typeof strict === "object" && strict !== null ? strict.bundlerFallback ?? "warn" : "warn";
+  } catch {
+    return "warn";
+  }
+}
+const EXTERNAL_PATTERNS = [
+  /^stx$/,
+  /^@stacksjs\/stx$/,
+  /^@stores$/,
+  /^stx\/stores$/,
+  /^@composables$/
+];
+export function hasUserImports(code) {
+  const fullImportRegex = /^[ \t]*import[ \t]+(?!type(?:[ \t]|{))[\s\S]*?\s+from\s+['"]([^'"]+)['"][ \t]*;?/gm;
+  let match;
+  while ((match = fullImportRegex.exec(code)) !== null) {
+    const source = match[1];
+    if (!EXTERNAL_PATTERNS.some((p) => p.test(source))) {
+      logBundlerDiagnostic("detected user import:", source);
+      return !0;
+    }
+  }
+  const sideEffectRegex = /^[ \t]*import[ \t]+['"]([^'"]+)['"]/gm;
+  while ((match = sideEffectRegex.exec(code)) !== null) {
+    const source = match[1];
+    if (/\.css(?:\?.*)?$/.test(source))
+      continue;
+    if (!EXTERNAL_PATTERNS.some((p) => p.test(source))) {
+      logBundlerDiagnostic("detected side-effect import:", source);
+      return !0;
+    }
+  }
+  return !1;
+}
+function probeModuleFile(basePath) {
+  const candidates = [
+    basePath,
+    `${basePath}.ts`,
+    `${basePath}.tsx`,
+    `${basePath}.js`,
+    `${basePath}.mjs`,
+    `${basePath}.jsx`,
+    path.join(basePath, "index.ts"),
+    path.join(basePath, "index.tsx"),
+    path.join(basePath, "index.js"),
+    path.join(basePath, "index.mjs")
+  ];
+  for (const candidate of candidates)
+    try {
+      if (fs.existsSync(candidate) && fs.statSync(candidate, { throwIfNoEntry: !1 })?.isFile())
+        return candidate;
+    } catch {}
+  return;
+}
+function createBundlePlugin(projectRoot, templateDir, tmpEntry, inputFiles) {
+  const resolveRelative = (importer, request) => {
+    const fromDir = importer === tmpEntry ? templateDir : path.dirname(importer), resolved = path.resolve(fromDir, request);
+    return probeModuleFile(resolved) ?? resolved;
+  };
+  return {
+    name: "stx-client-bundle",
+    setup(build) {
+      build.onResolve({ filter: /^(stx|@stacksjs\/stx)$/ }, (args) => ({
+        path: args.path,
+        external: !0
+      }));
+      build.onResolve({ filter: /^(@stores|@composables|stx\/stores)$/ }, (args) => ({
+        path: args.path,
+        external: !0
+      }));
+      build.onResolve({ filter: /^\// }, (args) => {
+        const resolved = probeModuleFile(args.path);
+        if (resolved) {
+          if (resolved !== tmpEntry)
+            inputFiles.add(resolved);
+          return { path: resolved };
+        }
+        return {
+          path: args.path,
+          external: !0
+        };
+      });
+      build.onResolve({ filter: /^\.\.?\// }, (args) => {
+        const resolved = resolveRelative(args.importer, args.path);
+        inputFiles.add(resolved);
+        return { path: resolved };
+      });
+      build.onResolve({ filter: /^[@~]\// }, (args) => {
+        const resolved = path.resolve(projectRoot, args.path.slice(2)), candidates = [
+          resolved,
+          `${resolved}.ts`,
+          `${resolved}.tsx`,
+          `${resolved}.js`,
+          `${resolved}.mjs`,
+          `${resolved}.jsx`,
+          path.join(resolved, "index.ts"),
+          path.join(resolved, "index.tsx"),
+          path.join(resolved, "index.js"),
+          path.join(resolved, "index.mjs")
+        ];
+        for (const candidate of candidates)
+          if (fs.existsSync(candidate) && fs.statSync(candidate, { throwIfNoEntry: !1 })?.isFile()) {
+            logBundlerDiagnostic(`resolved ${args.path[0]}/ import:`, args.path, "\u2192", candidate);
+            inputFiles.add(candidate);
+            return { path: candidate };
+          }
+        console.warn(`[stx:bundler] could not resolve ${args.path[0]}/ import:`, args.path);
+        return { path: resolved };
+      });
+      build.onLoad({ filter: /\.(?:[cm]?[jt]sx?|json)$/ }, (args) => {
+        const extension = path.extname(args.path).toLowerCase(), loader = extension === ".json" ? "json" : extension === ".tsx" ? "tsx" : extension === ".jsx" ? "jsx" : extension === ".ts" || extension === ".mts" || extension === ".cts" ? "ts" : "js";
+        if (args.path !== tmpEntry)
+          inputFiles.add(args.path);
+        return {
+          contents: fs.readFileSync(args.path, "utf8"),
+          loader
+        };
+      });
+    }
+  };
+}
+const inFlightBundles = new Map, bundleMemo = renderMemo(64), CLIENT_BUNDLE_QUEUE = Symbol.for("stx.client-bundle-build-queue");
+export function queueClientBundleBuild(task) {
+  const shared = globalThis, result = (shared[CLIENT_BUNDLE_QUEUE] ?? Promise.resolve()).then(task, task);
+  shared[CLIENT_BUNDLE_QUEUE] = result.then(() => {
+    return;
+  }, () => {
+    return;
+  });
+  return result;
+}
+export async function bundleClientScript(code, filePath, options = {}) {
+  const projectRoot = options.projectRoot || process.cwd(), minify = options.minify ?? !1, cacheDir = options.cacheDir || stateDir(projectRoot, "bundle-cache"), hasher = new Bun.CryptoHasher("md5");
+  hasher.update(`${BUNDLE_CACHE_VERSION}\x00${code}\x00${filePath}`);
+  const hash = hasher.digest("hex").slice(0, 12), cachePath = path.join(cacheDir, `${hash}.js`), remembered = bundleMemo.get(cachePath);
+  if (remembered) {
+    if (depsUnchanged(remembered.files)) {
+      logBundlerDiagnostic("memo hit:", hash);
+      const paths = remembered.files.map((dep) => dep.path);
+      recordBundleInputs(filePath, paths);
+      options.collectInputs?.push(...paths);
+      return remembered.code;
+    }
+    bundleMemo.delete(cachePath);
+    logBundlerDiagnostic("memo invalidated by dep change:", hash);
+  }
+  const depsPath = path.join(cacheDir, `${hash}.deps.json`), cacheFile = Bun.file(cachePath);
+  if (await cacheFile.exists()) {
+    const depsFile = Bun.file(depsPath);
+    let depsValid = !0, storedFiles = null;
+    if (await depsFile.exists())
+      try {
+        const stored = JSON.parse(await depsFile.text());
+        if (stored.metadataVersion !== BUNDLE_CACHE_METADATA_VERSION || !Array.isArray(stored.files))
+          depsValid = !1;
+        else
+          storedFiles = stored.files;
+        if (storedFiles && !depsUnchanged(storedFiles))
+          depsValid = !1;
+      } catch {
+        depsValid = !1;
+      }
+    if (depsValid) {
+      logBundlerDiagnostic("cache hit:", hash);
+      if (storedFiles) {
+        recordBundleInputs(filePath, storedFiles.map((dep) => dep.path));
+        options.collectInputs?.push(...storedFiles.map((dep) => dep.path));
+      }
+      const code = await cacheFile.text();
+      if (storedFiles)
+        bundleMemo.set(cachePath, { code, files: storedFiles });
+      return code;
+    }
+    logBundlerDiagnostic("cache invalidated by dep change:", hash);
+  }
+  const running = inFlightBundles.get(hash);
+  if (running) {
+    const shared = await running;
+    if (options.collectInputs)
+      options.collectInputs.push(...(bundleMemo.get(cachePath)?.files ?? []).map((dep) => dep.path));
+    return shared;
+  }
+  const build = queueClientBundleBuild(() => buildBundle(code, filePath, { projectRoot, minify, cacheDir, hash, cachePath, depsPath, collectInputs: options.collectInputs }));
+  inFlightBundles.set(hash, build);
+  try {
+    return await build;
+  } finally {
+    inFlightBundles.delete(hash);
+  }
+}
+async function buildBundle(code, filePath, options) {
+  const { projectRoot, minify, cacheDir, hash, cachePath, depsPath } = options, tmpDir = stateDir(projectRoot, "bundle-tmp"), tmpEntry = path.join(tmpDir, `${hash}.ts`), tmpOutDir = path.join(tmpDir, "out", hash);
+  fs.mkdirSync(tmpDir, { recursive: !0 });
+  fs.mkdirSync(tmpOutDir, { recursive: !0 });
+  const templateDir = path.dirname(filePath), declNames = new Set, declRegex = /^[ \t]*(export\s+)?(?:const|let|var)\s+(?:\{([^}]+)\}|(\w+))/gm, funcRegex = /^[ \t]*(export\s+)?(?:async\s+)?function\s+(\w+)/gm;
+  let dm;
+  while ((dm = declRegex.exec(code)) !== null) {
+    if (dm[1])
+      continue;
+    if (dm[2])
+      dm[2].split(",").forEach((n) => {
+        const t = destructuredLocalName(n);
+        if (t)
+          declNames.add(t);
+      });
+    else if (dm[3])
+      declNames.add(dm[3]);
+  }
+  while ((dm = funcRegex.exec(code)) !== null) {
+    if (dm[1])
+      continue;
+    declNames.add(dm[2]);
+  }
+  const exportLine = declNames.size > 0 ? `
+export { ${[...declNames].join(", ")} }` : "";
+  await Bun.write(tmpEntry, code + exportLine);
+  logBundlerDiagnostic("bundling:", hash, "from:", path.basename(filePath));
+  const inputFiles = new Set;
+  try {
+    const result = await Bun.build({
+      entrypoints: [tmpEntry],
+      outdir: tmpOutDir,
+      target: "browser",
+      format: "esm",
+      minify,
+      plugins: [createBundlePlugin(projectRoot, templateDir, tmpEntry, inputFiles)],
+      define: {
+        "process.env.NODE_ENV": minify ? '"production"' : '"development"',
+        ...getPublicEnvDefine()
+      },
+      root: projectRoot
+    });
+    if (!result.success) {
+      const failure = result.logs.filter((l) => l.level === "error").map((l) => l.message).join(", ") || `Unable to bundle ${path.basename(filePath)}`, details = describeBuildFailure(result.logs, filePath || void 0);
+      console.warn("[stx:bundler] build failed:", failure);
+      recordBundleFailure(filePath || "", failure, details);
+      if (resolveBundlerFallback() === "error")
+        throw Error(failure);
+      return code;
+    }
+    let bundled = "";
+    for (const output of result.outputs) {
+      bundled = await output.text();
+      break;
+    }
+    const exposedBindings = [];
+    for (const exp of bundled.matchAll(/^\s*export\s*\{([^}]*)\}\s*;?\s*$/gm))
+      for (const spec of exp[1].split(",")) {
+        const asMatch = spec.trim().match(/^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)$/);
+        if (asMatch) {
+          exposedBindings.push([asMatch[2], asMatch[1]]);
+          continue;
+        }
+        const name = spec.trim();
+        if (/^[A-Za-z_$][\w$]*$/.test(name))
+          exposedBindings.push([name, name]);
+      }
+    const externalImports = bundled.match(/^\s*import\s+[^;]+;?\s*$/gm) || [];
+    bundled = bundled.replace(/^\s*import\s+[^;]+;?\s*$/gm, "").replace(/^\s*export\s*\{[^}]*\}\s*;?\s*$/gm, "").replace(/^\s*export\s+default\s+.*$/gm, "").trim();
+    const namespace = `__stxBundle_${hash}`, returnedBindings = exposedBindings.map(([publicName, localName]) => `${JSON.stringify(publicName)}: ${localName}`).join(", "), publicDeclarations = exposedBindings.map(([publicName]) => `var ${publicName} = undefined;`).join(`
+`), publicAssignments = exposedBindings.map(([publicName]) => `${publicName} = ${namespace}[${JSON.stringify(publicName)}];`).join(`
+`);
+    bundled = `${externalImports.join(`
+`)}
+${publicDeclarations}
+var ${namespace} = (function() {
+${bundled}
+return { ${returnedBindings} };
+})();
+${publicAssignments}`.trim();
+    logBundlerDiagnostic("bundled:", hash, "output:", bundled.length, "bytes");
+    if (declNames.size > 0 && exposedBindings.length === 0) {
+      console.warn(`[stx:bundler] dropped every binding for ${path.basename(filePath)} (${hash}); serving the unbundled source and not caching this result`);
+      return code;
+    }
+    fs.mkdirSync(cacheDir, { recursive: !0 });
+    await Bun.write(cachePath, bundled);
+    const depsSnapshot = Array.from(inputFiles).map((p) => {
+      try {
+        return { path: p, mtimeMs: fs.statSync(p).mtimeMs };
+      } catch {
+        return null;
+      }
+    }).filter((d) => d !== null);
+    await Bun.write(depsPath, JSON.stringify({
+      metadataVersion: BUNDLE_CACHE_METADATA_VERSION,
+      files: depsSnapshot
+    }));
+    recordBundleInputs(filePath, depsSnapshot.map((dep) => dep.path));
+    options.collectInputs?.push(...depsSnapshot.map((dep) => dep.path));
+    bundleMemo.set(cachePath, { code: bundled, files: depsSnapshot });
+    await pruneBundleCache(cacheDir);
+    return bundled;
+  } catch (error) {
+    const details = describeBuildFailure(error, filePath || void 0), failure = formatBuildFailure(error, filePath || void 0);
+    console.warn(`[stx:bundler] error: ${failure}`);
+    recordBundleFailure(filePath || "", failure, details);
+    if (resolveBundlerFallback() === "error")
+      throw error;
+    return code;
+  } finally {
+    try {
+      fs.rmSync(tmpEntry, { force: !0 });
+      fs.rmSync(tmpOutDir, { recursive: !0, force: !0 });
+    } catch {}
+  }
+}
+function destructuredLocalName(entry) {
+  let name = entry.trim();
+  if (!name)
+    return null;
+  const eq = name.indexOf("=");
+  if (eq !== -1)
+    name = name.slice(0, eq).trim();
+  const colon = name.indexOf(":");
+  if (colon !== -1)
+    name = name.slice(colon + 1).trim();
+  if (name.startsWith("..."))
+    name = name.slice(3).trim();
+  return /^[A-Za-z_$][\w$]*$/.test(name) ? name : null;
+}