@webstir-io/webstir 0.1.0 → 0.1.2

package/src/test.ts

@@ -2,18 +2,27 @@ import path from 'node:path';
 import { mkdir, writeFile } from 'node:fs/promises';
 
 import type { ModuleManifest } from '@webstir-io/module-contract';
-import type { TestModule, RunnerSummary, TestRunResult, RuntimeFilter } from '@webstir-io/webstir-testing';
+import type {
+  TestModule,
+  RunnerSummary,
+  TestRunResult,
+  RuntimeFilter,
+} from '@webstir-io/webstir-testing';
 import type { BuildTargetKind, WorkspaceDescriptor } from './types.ts';
 
 import { compileTestModules } from './compile-tests.ts';
+import { materializeRepoLocalWorkspaceDependencies } from './external-workspace.ts';
 import { loadProvider } from './providers.ts';
-import { createWorkspaceRuntimeEnv } from './runtime.ts';
-import { readWorkspaceDescriptor } from './workspace.ts';
 import {
   applyRuntimeFilter,
   describeRuntimeFilter,
   normalizeRuntimeFilter,
-  createDefaultProviderRegistry,
+} from './runtime-filter.ts';
+import { createWorkspaceRuntimeEnv } from './runtime.ts';
+import { run as runFrontendTests } from './testing-runtime.ts';
+import { readWorkspaceDescriptor } from './workspace.ts';
+import {
+  createDefaultProviderRegistry as createPublishedProviderRegistry,
   discoverTestManifest,
 } from '@webstir-io/webstir-testing';
 
@@ -21,6 +30,7 @@ export interface RunTestOptions {
   readonly workspaceRoot: string;
   readonly rawArgs: readonly string[];
   readonly env?: Record<string, string | undefined>;
+  readonly quietInstall?: boolean;
 }
 
 export interface TestCommandResult {
@@ -33,6 +43,9 @@ export interface TestCommandResult {
 }
 
 export async function runTest(options: RunTestOptions): Promise<TestCommandResult> {
+  await materializeRepoLocalWorkspaceDependencies(options.workspaceRoot, {
+    installStdio: options.quietInstall ? 'pipe' : 'inherit',
+  });
   const runtime = parseRuntimeFlag(options.rawArgs, options.env);
   const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
   const builtTargets = selectBuildTargets(workspace.mode, runtime);
@@ -41,7 +54,11 @@ export async function runTest(options: RunTestOptions): Promise<TestCommandResul
     const provider = await loadProvider(target);
     const result = await provider.build({
       workspaceRoot: workspace.root,
-      env: createWorkspaceRuntimeEnv(workspace.root, target === 'backend' ? 'test' : 'build', options.env),
+      env: createWorkspaceRuntimeEnv(
+        workspace.root,
+        target === 'backend' ? 'test' : 'build',
+        options.env,
+      ),
       incremental: false,
     });
 
@@ -52,7 +69,9 @@ export async function runTest(options: RunTestOptions): Promise<TestCommandResul
 
   const manifest = await discoverTestManifest(workspace.root);
   const filteredManifest = applyRuntimeFilter(manifest, runtime);
-  const filterMessage = describeRuntimeFilter(runtime, manifest.modules.length, filteredManifest.modules.length) ?? undefined;
+  const filterMessage =
+    describeRuntimeFilter(runtime, manifest.modules.length, filteredManifest.modules.length) ??
+    undefined;
   await compileTestModules(workspace.root, filteredManifest.modules);
   const summary = await executeTestRun(filteredManifest.modules, workspace.root);
 
@@ -69,11 +88,17 @@ export async function runTest(options: RunTestOptions): Promise<TestCommandResul
 export function formatFailedTests(results: readonly TestRunResult[]): string[] {
   return results
     .filter((result) => !result.passed)
-    .map((result) => `${result.file}: ${result.name}${result.message ? ` — ${firstLine(result.message)}` : ''}`);
+    .map(
+      (result) =>
+        `${result.file}: ${result.name}${result.message ? ` — ${firstLine(result.message)}` : ''}`,
+    );
 }
 
-async function executeTestRun(modules: readonly TestModule[], workspaceRoot: string): Promise<RunnerSummary> {
-  const registry = createDefaultProviderRegistry();
+async function executeTestRun(
+  modules: readonly TestModule[],
+  workspaceRoot: string,
+): Promise<RunnerSummary> {
+  const registry = createPublishedProviderRegistry();
   const grouped = new Map<TestModule['runtime'], TestModule[]>();
 
   for (const module of modules) {
@@ -88,7 +113,10 @@ async function executeTestRun(modules: readonly TestModule[], workspaceRoot: str
   let summary = createEmptySummary();
 
   for (const [runtime, runtimeModules] of grouped) {
-    const provider = registry.get(runtime);
+    const provider =
+      runtime === 'frontend'
+        ? { id: '@webstir-io/webstir/frontend-runtime', runTests: runFrontendTests }
+        : registry.get(runtime);
     if (!provider) {
       continue;
     }
@@ -96,7 +124,11 @@ async function executeTestRun(modules: readonly TestModule[], workspaceRoot: str
     const files = runtimeModules
       .map((module) => module.compiledPath)
       .filter((compiledPath): compiledPath is string => typeof compiledPath === 'string');
-    const runtimeSummary = await withRuntimeEnv(runtime, workspaceRoot, async () => await provider.runTests(files));
+    const runtimeSummary = await withRuntimeEnv(
+      runtime,
+      workspaceRoot,
+      async () => await provider.runTests(files),
+    );
     summary = {
       passed: summary.passed + runtimeSummary.passed,
       failed: summary.failed + runtimeSummary.failed,
@@ -112,7 +144,7 @@ async function executeTestRun(modules: readonly TestModule[], workspaceRoot: str
 async function withRuntimeEnv<T>(
   runtime: TestModule['runtime'],
   workspaceRoot: string,
-  callback: () => Promise<T>
+  callback: () => Promise<T>,
 ): Promise<T> {
   if (runtime !== 'backend') {
     return await callback();
@@ -154,7 +186,10 @@ function createEmptySummary(): RunnerSummary {
   };
 }
 
-function selectBuildTargets(mode: WorkspaceDescriptor['mode'], runtime: RuntimeFilter): BuildTargetKind[] {
+function selectBuildTargets(
+  mode: WorkspaceDescriptor['mode'],
+  runtime: RuntimeFilter,
+): BuildTargetKind[] {
   if (runtime === 'frontend') {
     if (mode === 'spa' || mode === 'ssg' || mode === 'full') {
       return ['frontend'];
@@ -184,7 +219,7 @@ function selectBuildTargets(mode: WorkspaceDescriptor['mode'], runtime: RuntimeF
 
 function parseRuntimeFlag(
   rawArgs: readonly string[],
-  env: Record<string, string | undefined> = process.env
+  env: Record<string, string | undefined> = process.env,
 ): RuntimeFilter {
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
@@ -200,13 +235,16 @@ function parseRuntimeFlag(
   return normalizeRuntimeFilter(env.WEBSTIR_TEST_RUNTIME);
 }
 
-async function persistBackendManifest(workspaceRoot: string, manifest: ModuleManifest): Promise<void> {
+async function persistBackendManifest(
+  workspaceRoot: string,
+  manifest: ModuleManifest,
+): Promise<void> {
   const webstirDir = path.join(workspaceRoot, '.webstir');
   await mkdir(webstirDir, { recursive: true });
   await writeFile(
     path.join(webstirDir, 'backend-manifest.json'),
     `${JSON.stringify(manifest, null, 2)}\n`,
-    'utf8'
+    'utf8',
   );
 }
 

package/src/testing-runtime.ts

@@ -0,0 +1,273 @@
+import fs from 'node:fs';
+import Module from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import vm from 'node:vm';
+
+import { assert } from '@webstir-io/webstir-testing';
+import type { RunnerSummary, TestCallback, TestRunResult } from '@webstir-io/webstir-testing';
+
+interface RegisteredTest {
+  readonly name: string;
+  readonly fn: TestCallback;
+}
+
+type RequireFn = NodeJS.Require;
+type RunnerGlobal = typeof globalThis & {
+  __currentFile?: string;
+  test?: (name: string, callback?: TestCallback) => void;
+  assert?: typeof assert;
+};
+
+const registry = new Map<string, RegisteredTest[]>();
+const moduleExports = Object.freeze({
+  get test() {
+    return test;
+  },
+  get assert() {
+    return assert;
+  },
+});
+const runnerGlobal = globalThis as RunnerGlobal;
+const esmFallback = Symbol('esm-fallback');
+
+export function test(name: string, callback?: TestCallback): void {
+  const currentFile = runnerGlobal.__currentFile;
+  if (!currentFile) {
+    throw new Error('No current file set');
+  }
+
+  const safeCallback: TestCallback = callback ?? (async () => undefined);
+  const tests = registry.get(currentFile);
+  if (tests) {
+    tests.push({
+      name: String(name),
+      fn: safeCallback,
+    });
+    return;
+  }
+
+  registry.set(currentFile, [
+    {
+      name: String(name),
+      fn: safeCallback,
+    },
+  ]);
+}
+
+runnerGlobal.test = test;
+runnerGlobal.assert = assert;
+export { assert };
+
+export async function run(files: readonly string[]): Promise<RunnerSummary> {
+  const allResults: TestRunResult[] = [];
+  const start = Date.now();
+
+  for (const file of files) {
+    if (!fs.existsSync(file)) {
+      allResults.push({
+        name: '[missing compiled file]',
+        file,
+        passed: false,
+        message: 'Compiled file not found',
+        durationMs: 0,
+      });
+      continue;
+    }
+
+    const evalError = await evaluateModule(file);
+    if (evalError) {
+      allResults.push({
+        name: '[module evaluation]',
+        file,
+        passed: false,
+        message: evalError,
+        durationMs: 0,
+      });
+      continue;
+    }
+
+    const tests = registry.get(file) ?? [];
+    for (const entry of tests) {
+      const outcome = await runSingleTest(entry);
+      allResults.push({
+        name: entry.name,
+        file,
+        passed: outcome.passed,
+        message: outcome.message,
+        durationMs: outcome.durationMs,
+      });
+    }
+  }
+
+  let passed = 0;
+  let failed = 0;
+  for (const result of allResults) {
+    if (result.passed) {
+      passed += 1;
+    } else {
+      failed += 1;
+    }
+  }
+
+  return {
+    passed,
+    failed,
+    total: allResults.length,
+    durationMs: Date.now() - start,
+    results: allResults,
+  };
+}
+
+function createRuntimeRequire(file: string): RequireFn {
+  const baseRequire = Module.createRequire(file);
+  const runtimeRequire = ((specifier: string) => {
+    if (specifier === '@webstir-io/webstir-testing') {
+      return moduleExports;
+    }
+
+    return baseRequire(specifier);
+  }) as RequireFn;
+
+  const resolve = ((specifier: string, options?: Parameters<typeof baseRequire.resolve>[1]) => {
+    if (specifier === '@webstir-io/webstir-testing') {
+      return specifier;
+    }
+
+    return baseRequire.resolve(specifier, options);
+  }) as NodeJS.RequireResolve;
+
+  resolve.paths = baseRequire.resolve.paths;
+  runtimeRequire.resolve = resolve;
+  runtimeRequire.cache = baseRequire.cache;
+  runtimeRequire.main = baseRequire.main;
+  runtimeRequire.extensions = baseRequire.extensions;
+
+  return runtimeRequire;
+}
+
+async function evaluateModule(file: string): Promise<string | null> {
+  const code = fs.readFileSync(file, 'utf8');
+  const commonJsResult = evaluateCommonJsModule(file, code);
+
+  if (commonJsResult === null) {
+    return null;
+  }
+
+  if (commonJsResult === esmFallback) {
+    return await evaluateEsmModule(file);
+  }
+
+  return commonJsResult;
+}
+
+function evaluateCommonJsModule(file: string, code: string): string | typeof esmFallback | null {
+  const runtimeRequire = createRuntimeRequire(file);
+  const context = vm.createContext({
+    test,
+    assert,
+    globalThis,
+    console,
+    setTimeout,
+    clearTimeout,
+    require: runtimeRequire,
+    __dirname: path.dirname(file),
+    __filename: file,
+  });
+
+  runnerGlobal.__currentFile = file;
+  registry.set(file, []);
+
+  try {
+    const script = new vm.Script(code, { filename: file });
+    script.runInContext(context, { displayErrors: true });
+    return null;
+  } catch (error) {
+    if (isEsModuleSyntaxError(error)) {
+      return esmFallback;
+    }
+
+    return formatError(error);
+  } finally {
+    delete runnerGlobal.__currentFile;
+  }
+}
+
+async function evaluateEsmModule(file: string): Promise<string | null> {
+  const moduleUrl = pathToFileURL(file);
+  moduleUrl.searchParams.set('ts', Date.now().toString());
+
+  try {
+    runnerGlobal.__currentFile = file;
+    registry.set(file, []);
+    await import(moduleUrl.href);
+    return null;
+  } catch (error) {
+    return formatError(error);
+  } finally {
+    delete runnerGlobal.__currentFile;
+  }
+}
+
+function isEsModuleSyntaxError(error: unknown): boolean {
+  const name =
+    typeof error === 'object' && error !== null && 'name' in error
+      ? String((error as { name?: unknown }).name)
+      : '';
+  const message =
+    typeof error === 'object' && error !== null && 'message' in error
+      ? String((error as { message?: unknown }).message)
+      : '';
+
+  if (name !== 'SyntaxError' || message.length === 0) {
+    return false;
+  }
+
+  return (
+    message.includes('Cannot use import statement outside a module') ||
+    message.includes('Unexpected token') ||
+    message.includes('export') ||
+    message.includes('import call expects one or two arguments')
+  );
+}
+
+async function runSingleTest(
+  testCase: RegisteredTest,
+): Promise<{ passed: boolean; message: string | null; durationMs: number }> {
+  const start = Date.now();
+  try {
+    const result = testCase.fn();
+    if (isPromiseLike(result)) {
+      await result;
+    }
+
+    return {
+      passed: true,
+      message: null,
+      durationMs: Date.now() - start,
+    };
+  } catch (error) {
+    return {
+      passed: false,
+      message: formatError(error),
+      durationMs: Date.now() - start,
+    };
+  }
+}
+
+function isPromiseLike(value: unknown): value is Promise<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'then' in value &&
+    typeof (value as { then?: unknown }).then === 'function'
+  );
+}
+
+function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+
+  return String(error);
+}

package/src/types.ts

@@ -1,7 +1,4 @@
-import type {
-  ModuleBuildResult,
-  ModuleProvider,
-} from '@webstir-io/module-contract';
+import type { ModuleBuildResult, ModuleProvider } from '@webstir-io/module-contract';
 
 export const SUPPORTED_WORKSPACE_MODES = ['spa', 'ssg', 'api', 'full'] as const;
 

package/src/watch-events.ts

@@ -19,10 +19,16 @@ export interface HotUpdateAsset {
   readonly url: string;
 }
 
+export interface HotUpdateTarget {
+  readonly kind: 'boundary';
+  readonly id: string;
+}
+
 export interface HotUpdatePayload {
   readonly requiresReload: boolean;
   readonly modules: readonly HotUpdateAsset[];
   readonly styles: readonly HotUpdateAsset[];
+  readonly target?: HotUpdateTarget;
   readonly changedFile?: string;
   readonly fallbackReasons?: readonly string[];
   readonly stats?: {
@@ -74,16 +80,14 @@ export function collectWatchActions(payload: StructuredDiagnosticPayload): reado
   }
 
   const hotUpdate = readHotUpdatePayload(payload.data);
-  const changedFile = typeof hotUpdate?.changedFile === 'string' ? hotUpdate.changedFile : undefined;
+  const changedFile =
+    typeof hotUpdate?.changedFile === 'string' ? hotUpdate.changedFile : undefined;
   if (!hotUpdate || !changedFile) {
     return [{ type: 'status', status: 'success' }];
   }
 
   if (hotUpdate.requiresReload) {
-    return [
-      { type: 'status', status: 'hmr-fallback' },
-      { type: 'reload' },
-    ];
+    return [{ type: 'status', status: 'hmr-fallback' }, { type: 'reload' }];
   }
 
   if (hotUpdate.modules.length === 0 && hotUpdate.styles.length === 0) {
@@ -97,15 +101,19 @@ export function collectWatchActions(payload: StructuredDiagnosticPayload): reado
 }
 
 function isBuildStartDiagnostic(code: string): boolean {
-  return code === 'frontend.watch.starting' ||
+  return (
+    code === 'frontend.watch.starting' ||
     code === 'frontend.watch.reload' ||
-    code.endsWith('.build.start');
+    code.endsWith('.build.start')
+  );
 }
 
 function isBuildFailureDiagnostic(code: string): boolean {
-  return code === 'frontend.watch.unexpected' ||
+  return (
+    code === 'frontend.watch.unexpected' ||
     code === 'frontend.watch.command.failure' ||
-    code.endsWith('.build.failure');
+    code.endsWith('.build.failure')
+  );
 }
 
 function readHotUpdatePayload(data: Record<string, unknown> | undefined): HotUpdatePayload | null {
@@ -127,6 +135,7 @@ function readHotUpdatePayload(data: Record<string, unknown> | undefined): HotUpd
     requiresReload: payload.requiresReload,
     modules: readAssets(payload.modules),
     styles: readAssets(payload.styles),
+    target: readTarget(payload.target),
     changedFile: typeof payload.changedFile === 'string' ? payload.changedFile : undefined,
     fallbackReasons: Array.isArray(payload.fallbackReasons)
       ? payload.fallbackReasons.filter((value): value is string => typeof value === 'string')
@@ -155,12 +164,14 @@ function readAssets(value: unknown): readonly HotUpdateAsset[] {
       return [];
     }
 
-    return [{
-      type: asset.type,
-      path: asset.path,
-      relativePath: asset.relativePath,
-      url: asset.url,
-    }];
+    return [
+      {
+        type: asset.type,
+        path: asset.path,
+        relativePath: asset.relativePath,
+        url: asset.url,
+      },
+    ];
   });
 }
 
@@ -180,16 +191,34 @@ function readStats(value: unknown): HotUpdatePayload['stats'] | undefined {
   };
 }
 
+function readTarget(value: unknown): HotUpdateTarget | undefined {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+
+  const target = value as Record<string, unknown>;
+  if (target.kind !== 'boundary' || typeof target.id !== 'string' || target.id.trim() === '') {
+    return undefined;
+  }
+
+  return {
+    kind: 'boundary',
+    id: target.id,
+  };
+}
+
 function isStructuredDiagnosticPayload(value: unknown): value is StructuredDiagnosticPayload {
   if (typeof value !== 'object' || value === null) {
     return false;
   }
 
   const payload = value as Record<string, unknown>;
-  return payload.type === 'diagnostic' &&
+  return (
+    payload.type === 'diagnostic' &&
     typeof payload.code === 'string' &&
     typeof payload.kind === 'string' &&
     typeof payload.stage === 'string' &&
     typeof payload.severity === 'string' &&
-    typeof payload.message === 'string';
+    typeof payload.message === 'string'
+  );
 }

package/src/watch.ts

@@ -1,4 +1,5 @@
 import { runApiWatch } from './api-watch.ts';
+import { materializeRepoLocalWorkspaceDependencies } from './external-workspace.ts';
 import { runFrontendWatch } from './frontend-watch.ts';
 import { runFullWatch } from './full-watch.ts';
 import type { WorkspaceDescriptor } from './types.ts';
@@ -41,10 +42,13 @@ const defaultIo: WatchIo = {
 
 export async function runWatch(options: RunWatchOptions): Promise<void> {
   const io = options.io ?? defaultIo;
+  await materializeRepoLocalWorkspaceDependencies(options.workspaceRoot);
   const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
 
   switch (workspace.mode) {
     case 'spa':
+      await runFrontendWatch(workspace, options, io);
+      return;
     case 'ssg':
       await runFrontendWatch(workspace, options, io);
       return;
@@ -61,6 +65,6 @@ export async function runWatch(options: RunWatchOptions): Promise<void> {
 
 function throwUnsupportedWatchMode(workspace: WorkspaceDescriptor): never {
   throw new Error(
-    `Watch currently supports spa, ssg, api, and full workspaces only. "${workspace.name}" is ${workspace.mode}.`
+    `Watch currently supports spa, ssg, api, and full workspaces only. "${workspace.name}" is ${workspace.mode}.`,
   );
 }

package/src/workspace-watcher.ts

@@ -30,10 +30,7 @@ export class WorkspaceWatcher {
 
   public constructor(options: WorkspaceWatcherOptions) {
     this.workspaceRoot = path.resolve(options.workspaceRoot);
-    this.treeRoots = [
-      path.join(this.workspaceRoot, 'src'),
-      path.join(this.workspaceRoot, 'types'),
-    ];
+    this.treeRoots = [path.join(this.workspaceRoot, 'src'), path.join(this.workspaceRoot, 'types')];
     this.onEvent = options.onEvent;
     this.debounceMs = options.debounceMs ?? 75;
   }
@@ -112,7 +109,11 @@ export class WorkspaceWatcher {
     }
 
     for (const watchedDirectory of Array.from(this.treeWatchers.keys())) {
-      if (watchedDirectory !== root && watchedDirectory.startsWith(`${root}${path.sep}`) && !current.has(watchedDirectory)) {
+      if (
+        watchedDirectory !== root &&
+        watchedDirectory.startsWith(`${root}${path.sep}`) &&
+        !current.has(watchedDirectory)
+      ) {
         this.treeWatchers.get(watchedDirectory)?.close();
         this.treeWatchers.delete(watchedDirectory);
       }
@@ -234,7 +235,10 @@ async function collectDirectories(root: string): Promise<readonly string[]> {
   const stack = [path.resolve(root)];
 
   while (stack.length > 0) {
-    const current = stack.pop()!;
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
     directories.push(current);
 
     const entries = await readdir(current, { withFileTypes: true });

package/src/workspace.ts

@@ -25,7 +25,7 @@ export function parseWorkspaceMode(value: unknown): WorkspaceMode {
   }
 
   throw new Error(
-    `Unsupported webstir.mode "${value}". Expected one of: ${SUPPORTED_WORKSPACE_MODES.join(', ')}.`
+    `Unsupported webstir.mode "${value}". Expected one of: ${SUPPORTED_WORKSPACE_MODES.join(', ')}.`,
   );
 }
 
@@ -44,7 +44,9 @@ export async function readWorkspaceDescriptor(workspacePath: string): Promise<Wo
   try {
     packageJson = JSON.parse(rawPackageJson) as WorkspacePackageJson;
   } catch (error) {
-    throw new Error(`Workspace package.json at ${packageJsonPath} is not valid JSON.`, { cause: error });
+    throw new Error(`Workspace package.json at ${packageJsonPath} is not valid JSON.`, {
+      cause: error,
+    });
   }
 
   return {