@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.8 → 3.9.3-ultramodern.1

package/src/native-type-checker.ts

@@ -1,27 +1,226 @@
 import { execFile } from 'node:child_process';
-import { realpathSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import { refreshTsgoCheckerConfig } from '@modern-js/builder';
 import type { Rspack, RspackChain } from '@rsbuild/core';
+import { type ParseError, parse, printParseErrorCode } from 'jsonc-parser';
 
 const execute = promisify(execFile);
 const name = 'UltramodernNativeTypeChecker';
 
+export interface NativeTypeCheckerCommand {
+  executable: string;
+  args: readonly string[];
+}
+
+/** Launch the selected stable package through its declared public compiler bin. */
+export function resolveNativeTypeCheckerCommand(
+  packageJsonPath: string,
+): NativeTypeCheckerCommand {
+  const manifestFile = realpathSync(packageJsonPath);
+  const directory = path.dirname(manifestFile);
+  const manifest = JSON.parse(readFileSync(manifestFile, 'utf8')) as {
+    name?: unknown;
+    version?: unknown;
+    bin?: { tsc?: unknown };
+  };
+  if (manifest.name !== 'typescript' || manifest.version !== '7.0.2') {
+    throw new Error(
+      `${name} requires typescript@7.0.2; found ${String(manifest.name)}@${String(manifest.version)} at ${manifestFile}.`,
+    );
+  }
+  const bin = manifest.bin?.tsc;
+  if (typeof bin !== 'string' || !bin || path.isAbsolute(bin)) {
+    throw new Error(`${name} requires the selected package's public tsc bin.`);
+  }
+  const launcher = realpathSync(path.resolve(directory, bin));
+  const relative = path.relative(directory, launcher);
+  if (
+    !relative ||
+    path.isAbsolute(relative) ||
+    relative === '..' ||
+    relative.startsWith(`..${path.sep}`) ||
+    !statSync(launcher).isFile()
+  ) {
+    throw new Error(
+      `${name} public tsc bin must belong to its selected package.`,
+    );
+  }
+  return { executable: process.execPath, args: [launcher] };
+}
+
+interface TypeCheckerConfig {
+  compilerOptions?: Record<string, unknown>;
+  references?: Array<{ path: string }>;
+  [key: string]: unknown;
+}
+
 // Windows file events expand 8.3 aliases; register the same native path spelling.
-const watchDependencyPath = (file: string): string =>
-  process.platform === 'win32' ? realpathSync.native(file) : file;
+// A path that does not exist yet (a project tsconfig mid-edit) cannot be
+// realpathed; it is registered as spelled so its return still triggers a build.
+const watchDependencyPath = (file: string): string => {
+  if (process.platform !== 'win32') return file;
+  try {
+    return realpathSync.native(file);
+  } catch {
+    return file;
+  }
+};
+
+/**
+ * TS2875 means JSX compiles against a jsxImportSource whose runtime is not
+ * installed: usually components still authored for a previous renderer.
+ */
+export function missingJsxRuntimeHint(diagnostics: string): string {
+  const source =
+    /error TS2875: This JSX tag requires the module path '(.+?)\/jsx-(?:dev-)?runtime'/u.exec(
+      diagnostics,
+    )?.[1];
+  if (!source) return '';
+  return `\nHint: JSX compiles against jsxImportSource '${source}', the selected renderer's runtime, but '${source}/jsx-runtime' cannot be resolved from this app. If you changed \`renderer\` in modern.config, install that renderer's packages and port components authored for the previous renderer, or switch \`renderer\` back.\n`;
+}
 
 export class UltramodernNativeTypeChecker {
   constructor(
     private readonly options: {
-      compiler: () => string;
+      compiler: () => string | NativeTypeCheckerCommand;
       configFile: string;
       build: boolean;
+      configOverwrite?: TypeCheckerConfig;
     },
   ) {}
 
   async check(): Promise<void> {
-    const { configFile, build } = this.options;
+    const configFile = await this.projectConfigFile();
+    try {
+      await this.checkProject(configFile);
+    } finally {
+      this.removeProjection(configFile);
+    }
+  }
+
+  private async projectConfigFile(): Promise<string> {
+    const { configFile, configOverwrite } = this.options;
+    if (!configOverwrite) return configFile;
+    // Merge before native parsing: an overwrite may supply the inputs that
+    // make an otherwise empty project valid. A same-directory projection
+    // preserves the original extends, relative paths and project references.
+    const errors: ParseError[] = [];
+    const source = readFileSync(configFile, 'utf8');
+    const project: TypeCheckerConfig = parse(
+      source.charCodeAt(0) === 0xfeff ? source.slice(1) : source,
+      errors,
+      { allowTrailingComma: true },
+    );
+    if (errors.length) {
+      throw new Error(
+        `${name} requires valid JSONC in ${configFile}: ${errors
+          .map(
+            error => `${printParseErrorCode(error.error)} at ${error.offset}`,
+          )
+          .join(', ')}`,
+      );
+    }
+    if (!project || typeof project !== 'object' || Array.isArray(project)) {
+      throw new Error(`${name} requires a JSONC object in ${configFile}.`);
+    }
+    const projectedConfig: TypeCheckerConfig = {
+      ...project,
+      ...configOverwrite,
+      compilerOptions: {
+        ...project.compilerOptions,
+        ...configOverwrite.compilerOptions,
+      },
+    };
+    const projected = path.join(
+      path.dirname(configFile),
+      `.ultramodern-native-checker.${randomUUID()}.json`,
+    );
+    writeFileSync(projected, `${JSON.stringify(projectedConfig, null, 2)}\n`, {
+      flag: 'wx',
+    });
+    try {
+      const resolved: TypeCheckerConfig = JSON.parse(
+        await this.run(['--showConfig', '--project', projected]),
+      );
+      const options = resolved.compilerOptions ?? {};
+      if (
+        (this.options.build ||
+          options.incremental === true ||
+          options.composite === true) &&
+        !options.tsBuildInfoFile
+      ) {
+        // Native TypeScript derives the default from the config filename.
+        // Retain that original identity while this invocation-private config
+        // is alive; referenced projects still use their own configurations.
+        const original = configFile.slice(
+          0,
+          configFile.length - path.extname(configFile).length,
+        );
+        let buildInfo = original;
+        if (typeof options.outDir === 'string') {
+          const outDir = path.resolve(path.dirname(configFile), options.outDir);
+          buildInfo =
+            typeof options.rootDir === 'string'
+              ? path.resolve(
+                  outDir,
+                  path.relative(
+                    path.resolve(path.dirname(configFile), options.rootDir),
+                    original,
+                  ),
+                )
+              : path.join(outDir, path.basename(original));
+        }
+        projectedConfig.compilerOptions = {
+          ...projectedConfig.compilerOptions,
+          tsBuildInfoFile: `${buildInfo}.tsbuildinfo`,
+        };
+        writeFileSync(
+          projected,
+          `${JSON.stringify(projectedConfig, null, 2)}\n`,
+        );
+      }
+      return projected;
+    } catch (error) {
+      unlinkSync(projected);
+      throw error;
+    }
+  }
+
+  private removeProjection(configFile: string): void {
+    if (configFile !== this.options.configFile) unlinkSync(configFile);
+  }
+
+  private async checkProject(configFile: string): Promise<void> {
+    const { build } = this.options;
+    if (!build) {
+      const config = JSON.parse(
+        await this.run(['--showConfig', '--project', configFile]),
+      ) as { references?: { path: string }[] };
+      // Project mode consumes referenced declarations but never builds them.
+      // Prepare only the references using their own emit contracts, then keep
+      // the app itself in no-emit mode. This also refreshes stale declarations.
+      if (config.references?.length) {
+        await this.run([
+          '--build',
+          ...config.references.map(reference =>
+            path.resolve(path.dirname(configFile), reference.path),
+          ),
+          '--stopBuildOnErrors',
+          '--pretty',
+          'false',
+        ]);
+      }
+    }
     const args = build
       ? ['--build', configFile, '--stopBuildOnErrors']
       : ['--project', configFile, '--noEmit'];
@@ -30,35 +229,58 @@ export class UltramodernNativeTypeChecker {
 
   private async run(args: string[]): Promise<string> {
     try {
-      const result = await execute(this.options.compiler(), args, {
-        cwd: path.dirname(this.options.configFile),
-        maxBuffer: 16 * 1024 * 1024,
-      });
+      const selected = this.options.compiler();
+      const command =
+        typeof selected === 'string'
+          ? { executable: selected, args: [] }
+          : selected;
+      const result = await execute(
+        command.executable,
+        [...command.args, ...args],
+        {
+          cwd: path.dirname(this.options.configFile),
+          maxBuffer: 16 * 1024 * 1024,
+        },
+      );
       return result.stdout;
     } catch (cause) {
       const output = cause as { stdout?: string; stderr?: string };
       const diagnostics = `${output.stdout ?? ''}${output.stderr ?? ''}`;
       throw new Error(
-        `${name} failed:\n${diagnostics || (cause instanceof Error ? cause.message : String(cause))}`,
+        `${name} failed:\n${diagnostics || (cause instanceof Error ? cause.message : String(cause))}${missingJsxRuntimeHint(diagnostics)}`,
         { cause },
       );
     }
   }
 
-  private async watchInputs(): Promise<Set<string>> {
+  private async watchInputs(configFile: string): Promise<{
+    inputs: Set<string>;
+    missing: Set<string>;
+  }> {
     const inputs = new Set<string>();
-    const projects = [this.options.configFile];
+    const missing = new Set<string>();
+    const projects = [configFile];
     const visited = new Set<string>();
     for (const configFile of projects) {
       if (visited.has(configFile)) continue;
       visited.add(configFile);
-      inputs.add(configFile);
-      const config = JSON.parse(
-        await this.run(['--showConfig', '--project', configFile]),
-      ) as {
-        files?: string[];
-        references?: { path: string }[];
-      };
+      // Registered before it is parsed: a referenced config that is absent or
+      // unparsable right now must still be watched, or creating or repairing
+      // it never re-triggers the compilation. `check()` reports the error.
+      if (configFile === this.options.configFile || configFile !== projects[0])
+        inputs.add(configFile);
+      if (!existsSync(configFile)) {
+        missing.add(configFile);
+        continue;
+      }
+      let config: { files?: string[]; references?: { path: string }[] };
+      try {
+        config = JSON.parse(
+          await this.run(['--showConfig', '--project', configFile]),
+        );
+      } catch {
+        continue;
+      }
       const directory = path.dirname(configFile);
       for (const file of config.files ?? [])
         inputs.add(path.resolve(directory, file));
@@ -71,7 +293,7 @@ export class UltramodernNativeTypeChecker {
         );
       }
     }
-    return inputs;
+    return { inputs, missing };
   }
 
   apply(compiler: Rspack.Compiler): void {
@@ -81,9 +303,34 @@ export class UltramodernNativeTypeChecker {
           compilation.fileDependencies.add(
             watchDependencyPath(this.options.configFile),
           );
-          for (const file of await this.watchInputs())
-            compilation.fileDependencies.add(watchDependencyPath(file));
-          await this.check();
+          // A generated checker config restates values TypeScript does not
+          // inherit through `extends` (project references above all). Rebuild
+          // it from the project's own tsconfig before every check, and watch
+          // that tsconfig, so an edit during `modern dev` reaches the next
+          // compilation instead of the next restart.
+          const projectConfigFile = refreshTsgoCheckerConfig(
+            this.options.configFile,
+          );
+          if (projectConfigFile) {
+            const watched = watchDependencyPath(projectConfigFile);
+            compilation.fileDependencies.add(watched);
+            // Absent mid-edit: a missing dependency makes its (re)appearance
+            // a rebuild trigger, so the dev server recovers on its own.
+            if (!existsSync(projectConfigFile)) {
+              compilation.missingDependencies.add(watched);
+            }
+          }
+          const configFile = await this.projectConfigFile();
+          try {
+            const { inputs, missing } = await this.watchInputs(configFile);
+            for (const file of inputs)
+              compilation.fileDependencies.add(watchDependencyPath(file));
+            for (const file of missing)
+              compilation.missingDependencies.add(watchDependencyPath(file));
+            await this.checkProject(configFile);
+          } finally {
+            this.removeProjection(configFile);
+          }
         } catch (cause) {
           compilation.errors.push(
             new Error(cause instanceof Error ? cause.message : String(cause), {
@@ -96,15 +343,22 @@ export class UltramodernNativeTypeChecker {
   }
 }
 
-/** Preserve project-reference emit contracts in the native Effect compiler. */
+/** Preserve project-reference emit contracts in the selected native compiler. */
 export function configureUltramodernTypeChecker(
   chain: RspackChain,
   pluginId: string,
-  resolveCompiler: (configFile: string) => string,
+  resolveCompiler: (configFile: string) => string | NativeTypeCheckerCommand,
 ): void {
   if (!chain.plugins.has(pluginId)) return;
   const options = chain.plugin(pluginId).get('args')?.[0] as
-    | { typescript?: { configFile?: string; build?: boolean; tsgo?: boolean } }
+    | {
+        typescript?: {
+          configFile?: string;
+          build?: boolean;
+          tsgo?: boolean;
+          configOverwrite?: TypeCheckerConfig;
+        };
+      }
     | undefined;
   const typescript = options?.typescript;
   if (typescript?.tsgo === false) return;
@@ -117,6 +371,7 @@ export function configureUltramodernTypeChecker(
       build: typescript.build === true,
       compiler: () => resolveCompiler(configFile),
       configFile,
+      configOverwrite: typescript.configOverwrite,
     },
   ]);
 }

package/src/policy-defaults.ts

@@ -0,0 +1,157 @@
+import {
+  collectRuntimePackageModuleDirectories,
+  createRuntimePackageResolutionPlugin,
+} from './runtime-package-resolution';
+
+/**
+ * The fork's renderer policy (head rendering, HTML template assembly and asset
+ * ordering) and server policy (localised loaders, error responses, telemetry,
+ * module-federation CSS and asset cache headers, static serving) are the
+ * default behaviour of an UltraModern.js app.
+ *
+ * They live in their own packages so they can also be composed explicitly, but
+ * a plain `appTools()` app gets them without opting in — that is what this fork
+ * has always done. Pass `appTools({ rendererExtensions: false })` or
+ * `appTools({ serverExtensions: false })` to run without them.
+ */
+export const RENDERER_EXTENSIONS_PACKAGE =
+  '@modern-js/runtime-renderer-extensions';
+
+export const RENDERER_EXTENSIONS_PLUGIN_NAME = 'rendererHead';
+
+export const SERVER_EXTENSIONS_PLUGIN_NAME =
+  '@modern-js/app-tools/server-plugin';
+
+export const ULTRAMODERN_SERVER_EXTENSIONS_PLUGIN_NAME =
+  '@modern-js/ultramodern-app-tools/server-plugin';
+
+export interface PolicyDefaultsOptions {
+  /** Default `true`. Set to `false` to drop the fork's renderer policy. */
+  rendererExtensions?: boolean;
+  /** Default `true`. Set to `false` to drop the fork's server policy. */
+  serverExtensions?: boolean;
+}
+
+/** The native package that explicitly composes the policy. */
+export interface PolicyDefaultsComposition {
+  pluginName?: string;
+  serverPluginName?: string;
+  /** Additional runtime packages that share the resolution fallback. */
+  runtimePackages?: readonly string[];
+  /** Resolve runtime packages from the composing package. */
+  registrarUrl?: string;
+}
+
+type RuntimePluginDescriptor = {
+  name?: string;
+  path: string;
+  config?: unknown;
+};
+
+type ServerPluginDescriptor = { name: string };
+
+/**
+ * The subset of the CLI plugin API these defaults use. Typed structurally, and
+ * loosely at the hook boundary, so this package stays free of a dependency on
+ * the solution that consumes it — which depends on this one.
+ */
+export interface PolicyDefaultsPluginApi {
+  _internalRuntimePlugins(fn: (input: any) => any): void;
+  _internalServerPlugins(fn: (input: any) => any): void;
+  modifyResolvedConfig(fn: (config: any) => any): void;
+}
+
+type RuntimePluginsInput = {
+  entrypoint: unknown;
+  plugins: RuntimePluginDescriptor[];
+};
+
+type ServerPluginsInput = { plugins: ServerPluginDescriptor[] };
+
+export const POLICY_DEFAULTS_PLUGIN_NAME =
+  '@modern-js/ultramodern-policy-defaults';
+
+/** Registers the fork's default renderer and server policy. */
+export const applyPolicyDefaults = (
+  api: PolicyDefaultsPluginApi,
+  options: PolicyDefaultsOptions = {},
+  composition: PolicyDefaultsComposition = {},
+): void => {
+  if (options.rendererExtensions !== false) {
+    api._internalRuntimePlugins(
+      ({ entrypoint, plugins }: RuntimePluginsInput) => {
+        // An explicit composition (`ultramodernAppTools()`) may already have
+        // registered it; the descriptor list must stay free of duplicates.
+        if (
+          !plugins.some(plugin => plugin.path === RENDERER_EXTENSIONS_PACKAGE)
+        ) {
+          plugins.push({
+            name: RENDERER_EXTENSIONS_PLUGIN_NAME,
+            path: RENDERER_EXTENSIONS_PACKAGE,
+            config: {},
+          });
+        }
+        return { entrypoint, plugins };
+      },
+    );
+  }
+
+  const runtimePackages = [
+    ...(options.rendererExtensions !== false
+      ? [RENDERER_EXTENSIONS_PACKAGE]
+      : []),
+    ...(composition.runtimePackages ?? []).filter(
+      packageName => packageName !== RENDERER_EXTENSIONS_PACKAGE,
+    ),
+  ];
+  const moduleDirectories = collectRuntimePackageModuleDirectories(
+    runtimePackages,
+    composition.registrarUrl ?? import.meta.url,
+  );
+  if (moduleDirectories.length > 0) {
+    api.modifyResolvedConfig(config => ({
+      ...config,
+      builderPlugins: [
+        ...(config.builderPlugins ?? []),
+        createRuntimePackageResolutionPlugin(moduleDirectories),
+      ],
+    }));
+  }
+
+  if (options.serverExtensions !== false) {
+    const serverPluginName =
+      composition.serverPluginName ?? SERVER_EXTENSIONS_PLUGIN_NAME;
+    api._internalServerPlugins(({ plugins }: ServerPluginsInput) => {
+      if (
+        !plugins.some(
+          plugin =>
+            plugin.name === serverPluginName ||
+            plugin.name === SERVER_EXTENSIONS_PLUGIN_NAME ||
+            plugin.name === ULTRAMODERN_SERVER_EXTENSIONS_PLUGIN_NAME,
+        )
+      ) {
+        plugins.push({ name: serverPluginName });
+      }
+      return { plugins };
+    });
+  }
+};
+
+/**
+ * The fork defaults as a CLI plugin.
+ *
+ * The descriptor this registers may land before the ones it wraps — CLI
+ * ordering cannot be constrained here without a cycle, because the plugins
+ * that emit those descriptors are themselves ordered after `appTools()`.
+ * Ordering is settled on the runtime side instead: `rendererHeadPlugin`
+ * declares the runtime plugins that run before it.
+ */
+export const createPolicyDefaultsPlugin = (
+  options: PolicyDefaultsOptions = {},
+  composition: PolicyDefaultsComposition = {},
+) => ({
+  name: composition.pluginName ?? POLICY_DEFAULTS_PLUGIN_NAME,
+  setup(api: PolicyDefaultsPluginApi) {
+    applyPolicyDefaults(api, options, composition);
+  },
+});

package/src/release-envelope/canonical.ts

@@ -1,8 +1,7 @@
 import { createHash } from 'node:crypto';
-import type {
-  MicroVerticalReleaseEnvelope,
-  MicroVerticalReleaseEnvelopePayload,
-} from './types';
+import type { ReleaseEnvelope, ReleaseEnvelopePayload } from './types';
+
+export { releaseEnvelopePayload } from './contract.mjs';
 
 type CanonicalValue =
   | null
@@ -31,27 +30,16 @@ const serializeCanonicalValue = (value: CanonicalValue): string => {
     .join(',')}}`;
 };
 
-export const releaseEnvelopePayload = (
-  envelope: MicroVerticalReleaseEnvelope,
-): MicroVerticalReleaseEnvelopePayload => ({
-  schemaVersion: envelope.schemaVersion,
-  kind: envelope.kind,
-  target: envelope.target,
-  identity: envelope.identity,
-  artifacts: envelope.artifacts,
-  surfaces: envelope.surfaces,
-});
-
 export const canonicalSerializeMicroVerticalReleaseEnvelopePayload = (
-  payload: MicroVerticalReleaseEnvelopePayload,
+  payload: ReleaseEnvelopePayload,
 ) => serializeCanonicalValue(payload as unknown as CanonicalValue);
 
 export const canonicalSerializeMicroVerticalReleaseEnvelope = (
-  envelope: MicroVerticalReleaseEnvelope,
+  envelope: ReleaseEnvelope,
 ) => serializeCanonicalValue(envelope as unknown as CanonicalValue);
 
 export const digestMicroVerticalReleaseEnvelopePayload = (
-  payload: MicroVerticalReleaseEnvelopePayload,
+  payload: ReleaseEnvelopePayload,
 ) =>
   createHash('sha256')
     .update(canonicalSerializeMicroVerticalReleaseEnvelopePayload(payload))

package/src/release-envelope/contract.mjs

@@ -0,0 +1,28 @@
+export const MICROVERTICAL_RELEASE_ENVELOPE_SCHEMA_VERSION =
+  /** @type {const} */ (5);
+
+export const MICROVERTICAL_RELEASE_ENVELOPE_KIND = /** @type {const} */ (
+  'ultramodern-target-microvertical-release-envelope'
+);
+
+export const SHELL_RELEASE_ENVELOPE_KIND = /** @type {const} */ (
+  'ultramodern-target-shell-release-envelope'
+);
+
+/**
+ * @param {import('./types.js').ReleaseEnvelope} envelope
+ * @returns {import('./types.js').ReleaseEnvelopePayload}
+ */
+export const releaseEnvelopePayload = envelope => {
+  const payload = {
+    schemaVersion: envelope.schemaVersion,
+    target: envelope.target,
+    identity: envelope.identity,
+    ...(envelope.ui ? { ui: envelope.ui } : {}),
+    artifacts: envelope.artifacts,
+  };
+  if (envelope.kind === SHELL_RELEASE_ENVELOPE_KIND) {
+    return { ...payload, kind: envelope.kind, surfaces: envelope.surfaces };
+  }
+  return { ...payload, kind: envelope.kind, surfaces: envelope.surfaces };
+};