@pulse-compute/wasm-compiler 0.0.0 → 1.0.0-beta.2

package/src/codegen/handler-bindings-ts.js

@@ -0,0 +1,298 @@
+'use strict';
+
+const path = require('node:path');
+const { getDefaultArtifactsDir } = require('@pulse-compute/wasm-build-support/artifacts-dir');
+const crypto = require('node:crypto');
+const { PACKAGE_VERSION, normalizeArtifact, stableFileName } = require('../diagnostics.js');
+
+const HANDLER_BINDINGS_VERSION = 'pulsewasm.handler-bindings.v1';
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function tsJson(value) {
+  return JSON.stringify(value, null, 2)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+}
+
+function header() {
+  return [
+    '/*',
+    ' * Generated by PulseWasm Phase 8B.',
+    ' * Do not edit by hand.',
+    ' *',
+    ' * This file is generated from dispatch-table.json + handler-table.json only.',
+    ' * It must not re-read user source or re-infer route semantics.',
+    ' */',
+    ''
+  ].join('\n');
+}
+
+function makeFile(file, text) {
+  return {
+    file,
+    bytes: Buffer.byteLength(text, 'utf8'),
+    sha256: sha256(text),
+    text
+  };
+}
+
+function stableIdToIdentifier(id) {
+  const cleaned = String(id || '').replace(/[^A-Za-z0-9_$]/g, '_');
+  return /^[A-Za-z_$]/.test(cleaned) ? cleaned : `handler_${cleaned}`;
+}
+
+function pathWithoutTsExtension(filePath) {
+  return filePath.replace(/\.(mts|cts|tsx|ts)$/i, '');
+}
+
+function relativeImportSpecifier({ fromDir, toFile }) {
+  let rel = path.relative(fromDir, toFile).replace(/\\/g, '/');
+  if (!rel.startsWith('.')) rel = `./${rel}`;
+  return pathWithoutTsExtension(rel);
+}
+
+function findHandler(handlerTable, id) {
+  return (handlerTable?.handlers || []).find((entry) => entry.id === id);
+}
+
+function displayName(entry, slot) {
+  return entry?.localName || entry?.exportName || slot?.name || entry?.inlineName || entry?.id || slot?.id;
+}
+
+function bindingDiagnosticsForSlot(slot, entry) {
+  const name = displayName(entry, slot);
+  const loc = entry?.loc || slot?.loc || { file: entry?.file || slot?.file || '<handler>' };
+  const diagnostics = [];
+
+  if (!entry) {
+    diagnostics.push({
+      pass: 'handler-bindings',
+      code: 'PULSEWASM_HANDLER_BINDING_UNKNOWN_HANDLER',
+      severity: 'error',
+      message: `Unable to find handler table entry for dispatch handler slot ${slot?.slot ?? '<unknown>'}.`,
+      hint: 'Regenerate dispatch-table.json and handler-table.json from the same build.',
+      loc
+    });
+    return diagnostics;
+  }
+
+  if (!entry.declaration?.topLevel) {
+    diagnostics.push({
+      pass: 'handler-bindings',
+      code: 'PULSEWASM_HANDLER_BINDING_INLINE_UNSUPPORTED',
+      severity: 'error',
+      message: `Handler "${name}" is inline and cannot be imported into generated handler-slot bindings.`,
+      hint: 'Move the handler to an exported top-level function declaration or exported const function/arrow expression.',
+      loc
+    });
+  }
+
+  if (!entry.declaration?.exported) {
+    diagnostics.push({
+      pass: 'handler-bindings',
+      code: 'PULSEWASM_HANDLER_BINDING_NOT_EXPORTED',
+      severity: 'error',
+      message: `Handler "${name}" is not exported, so generated dispatch cannot bind it by import.`,
+      hint: 'Export every handler used by PulseWasm codegen, for example `export function handler(ctx, next) {}`.',
+      loc
+    });
+  }
+
+  if (!entry.exportName && entry.declaration?.exported) {
+    diagnostics.push({
+      pass: 'handler-bindings',
+      code: 'PULSEWASM_HANDLER_BINDING_EXPORT_NAME_MISSING',
+      severity: 'error',
+      message: `Handler "${name}" is marked exported but no export name was recorded.`,
+      hint: 'Use a direct named export in the same module as the route registration.',
+      loc
+    });
+  }
+
+  return diagnostics;
+}
+
+function buildHandlerBindingsSource(bindings) {
+  const importsByFile = new Map();
+  for (const binding of bindings) {
+    const list = importsByFile.get(binding.importPath) || [];
+    list.push(binding);
+    importsByFile.set(binding.importPath, list);
+  }
+
+  const importLines = Array.from(importsByFile.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([importPath, list]) => {
+      const specifiers = list
+        .slice()
+        .sort((a, b) => a.exportName.localeCompare(b.exportName) || a.bindingName.localeCompare(b.bindingName))
+        .map((binding) => `${binding.exportName} as ${binding.bindingName}`)
+        .join(', ');
+      return `import { ${specifiers} } from ${JSON.stringify(importPath)}`;
+    })
+    .join('\n');
+
+  const bindingMeta = bindings.map((binding) => ({
+    slot: binding.slot,
+    id: binding.id,
+    name: binding.name,
+    exportName: binding.exportName,
+    bindingName: binding.bindingName,
+    roles: binding.roles,
+    kind: binding.kind,
+    file: binding.file,
+    importPath: binding.importPath,
+    signature: binding.signature
+  }));
+
+  const entries = bindings
+    .map((binding) => `  {
+    slot: ${binding.slot},
+    id: ${JSON.stringify(binding.id)},
+    name: ${JSON.stringify(binding.name)},
+    exportName: ${JSON.stringify(binding.exportName)},
+    bindingName: ${JSON.stringify(binding.bindingName)},
+    roles: ${tsJson(binding.roles)},
+    kind: ${JSON.stringify(binding.kind)},
+    file: ${JSON.stringify(binding.file)},
+    importPath: ${JSON.stringify(binding.importPath)},
+    signature: ${tsJson(binding.signature)},
+    handler: ${binding.bindingName} as PulseHandler
+  }`)
+    .join(',\n');
+
+  return `${header()}${importLines ? `${importLines}\n\n` : ''}export type PulseNext = (...args: unknown[]) => void
+export type PulseHandler = (...args: unknown[]) => unknown
+
+export type BoundHandlerSlot = {
+  readonly slot: number
+  readonly id: string
+  readonly name: string
+  readonly exportName: string
+  readonly bindingName: string
+  readonly roles: readonly string[]
+  readonly kind: string
+  readonly file: string
+  readonly importPath: string
+  readonly signature: {
+    readonly async: boolean
+    readonly generator: boolean
+    readonly paramCount: number
+    readonly params: readonly string[]
+    readonly nonIdentifierParams: readonly string[]
+    readonly returnsPromise: boolean
+  }
+  readonly handler: PulseHandler
+}
+
+export const HANDLER_BINDINGS_META = ${tsJson(bindingMeta)} as const
+
+export const HANDLER_SLOT_BINDINGS = [
+${entries}
+] as const satisfies readonly BoundHandlerSlot[]
+
+export const HANDLER_SLOT_MAP: ReadonlyMap<number, PulseHandler> = new Map(
+  HANDLER_SLOT_BINDINGS.map((binding) => [binding.slot, binding.handler] as const)
+)
+
+export const HANDLER_ID_MAP: ReadonlyMap<string, PulseHandler> = new Map(
+  HANDLER_SLOT_BINDINGS.map((binding) => [binding.id, binding.handler] as const)
+)
+
+export function getHandlerBySlot(slot: number): PulseHandler | undefined {
+  return HANDLER_SLOT_MAP.get(slot)
+}
+
+export function getHandlerById(id: string): PulseHandler | undefined {
+  return HANDLER_ID_MAP.get(id)
+}
+
+export function assertHandlerBindingCoverage(expectedSlots: readonly number[]): void {
+  for (const slot of expectedSlots) {
+    if (!HANDLER_SLOT_MAP.has(slot)) {
+      throw new Error('Missing generated handler binding for slot ' + slot)
+    }
+  }
+}
+`;
+}
+
+function buildTypeScriptHandlerBindings(dispatchTable, handlerTable, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const outDir = options.outDir ? path.resolve(cwd, options.outDir) : getDefaultArtifactsDir(cwd);
+  const generatedDir = path.resolve(outDir, 'generated');
+  const diagnostics = [];
+  const slots = dispatchTable?.handlerSlots || [];
+  const bindings = [];
+
+  for (const slot of slots) {
+    const entry = findHandler(handlerTable, slot.id);
+    diagnostics.push(...bindingDiagnosticsForSlot(slot, entry));
+    if (!entry || !entry.declaration?.topLevel || !entry.declaration?.exported || !entry.exportName) continue;
+
+    const sourceFile = path.resolve(cwd, entry.file);
+    const importPath = relativeImportSpecifier({ fromDir: generatedDir, toFile: sourceFile });
+    const bindingName = stableIdToIdentifier(entry.id);
+    bindings.push({
+      slot: slot.slot,
+      id: entry.id,
+      name: displayName(entry, slot),
+      exportName: entry.exportName,
+      bindingName,
+      roles: entry.roles || slot.roles || [],
+      kind: entry.kind,
+      file: stableFileName(sourceFile, cwd),
+      importPath,
+      signature: entry.signature || slot.signature || {},
+      loc: entry.loc || slot.loc
+    });
+  }
+
+  const file = makeFile('generated/handler-slots.ts', buildHandlerBindingsSource(bindings));
+  const artifact = normalizeArtifact({
+    version: HANDLER_BINDINGS_VERSION,
+    generatedBy: options.generatedBy || PACKAGE_VERSION,
+    source: dispatchTable?.source,
+    sourceDispatchTableVersion: dispatchTable?.version,
+    handlerTableVersion: handlerTable?.version,
+    policy: {
+      phase: '8B',
+      sourceOfTruth: 'dispatch-table.json + handler-table.json',
+      reReadsSource: false,
+      reInfersRouteSemantics: false,
+      requiresExportedTopLevelHandlers: true,
+      inlineHandlersSupported: false,
+      invocationHarness: false,
+      wasmCodegen: false
+    },
+    output: {
+      language: 'typescript',
+      module: 'esm',
+      directory: 'generated',
+      files: [{ file: file.file, bytes: file.bytes, sha256: file.sha256 }]
+    },
+    bindings: bindings.map(({ loc, ...binding }) => binding),
+    summary: {
+      handlerSlots: slots.length,
+      bindings: bindings.length,
+      diagnostics: diagnostics.length,
+      files: 1
+    }
+  }, cwd);
+
+  return {
+    version: HANDLER_BINDINGS_VERSION,
+    artifact,
+    files: [file],
+    diagnostics
+  };
+}
+
+module.exports = {
+  HANDLER_BINDINGS_VERSION,
+  buildTypeScriptHandlerBindings
+};

package/src/codegen/handler-library-contracts.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-library-kit/compiler').handlerLibraryContracts;

package/src/codegen/host-capabilities.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-library-kit/compiler').hostCapabilities;

package/src/codegen/host-runtime-kernel.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-host-runtime/compiler/host-runtime-kernel');

package/src/codegen/integrated-compiled-app.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-runtime-core-as/compiler/integrated-compiled-app');

package/src/codegen/json-body.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-host-runtime/compiler/json-body');

package/src/codegen/library-sidecars.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('@pulse-compute/wasm-library-kit/compiler').librarySidecars;