@pulse-compute/wasm-build-support 0.0.0 → 1.0.0-beta.1

package/README.md

@@ -1,3 +1,28 @@
 # @pulse-compute/wasm-build-support
 
-This is an inert namespace-bootstrap package. It contains no executable code.
+<!-- pulse-package-status:start -->
+> **Support tier:** Implementation/transitive surface<br>
+> **Audience:** Pulse release-set and compiler maintainers.<br>
+> **Install directly:** No for application projects; it is installed transitively where required.<br>
+> **Supported entry points:** `None for application authors.`<br>
+> **Stability:** Internal release-set interface; exported modules may change with compiler implementation needs.<br>
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.1/packages/implementation-packages/)
+>
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.1` package policy.
+<!-- pulse-package-status:end -->
+
+Shared build-time helpers for PulseWasm package-owned builders.
+
+This package is intentionally build/tooling scoped. It owns utilities that future package-owned compiler surfaces need without importing `@pulse-compute/wasm-compiler` internals.
+
+## Exposed modules
+
+- `artifactsDir` → canonical `wasm/artifacts` directory resolution helpers.
+- `assemblyscriptCompile` → AssemblyScript compiler resolution and compile-smoke helper.
+- `files` → shared slash normalization, SHA-256, truncation, ANSI stripping, and file-record helpers.
+
+## Boundary rules
+
+- May depend on `@pulse-compute/wasm-contracts` for diagnostics/artifact normalization.
+- Must not depend on `@pulse-compute/wasm-compiler`.
+- Must not own the `assemblyscript` dependency; AS is resolved from the caller workspace/package.

package/package.json

@@ -1,15 +1,39 @@
 {
   "name": "@pulse-compute/wasm-build-support",
-  "version": "0.0.0",
-  "description": "Inert namespace bootstrap for Pulse.",
+  "version": "1.0.0-beta.1",
   "license": "Apache-2.0",
+  "engines": {
+    "node": "^22.14.0 || ^24.0.0"
+  },
+  "description": "Shared build-time helpers for PulseWasm package-owned builders.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./artifacts-dir": "./src/artifacts-dir.js",
+    "./assemblyscript-compile": "./src/assemblyscript-compile.js",
+    "./native-optimization": "./src/native-optimization.js",
+    "./files": "./src/files.js"
+  },
+  "dependencies": {
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
+    "src",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "bootstrap"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulse-compute/pulse.git",
+    "directory": "wasm/packages/build-support"
+  },
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.1/packages/implementation-packages/",
+  "bugs": {
+    "url": "https://github.com/pulse-compute/pulse/issues"
   }
-}
+}

package/src/artifacts-dir.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function getBuildSupportPackageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+function getWasmRoot() {
+  const packageRoot = getBuildSupportPackageRoot();
+  const candidate = path.resolve(packageRoot, '..', '..');
+  const manifestPath = path.join(candidate, 'package.json');
+  if (path.basename(path.dirname(packageRoot)) === 'packages' && fs.existsSync(manifestPath)) {
+    return candidate;
+  }
+  return undefined;
+}
+
+function getDefaultArtifactsDir(cwd = process.cwd()) {
+  if (process.env.PULSEWASM_ARTIFACTS_DIR) {
+    return path.resolve(cwd, process.env.PULSEWASM_ARTIFACTS_DIR);
+  }
+  const wasmRoot = getWasmRoot();
+  if (wasmRoot) {
+    return path.join(wasmRoot, 'artifacts');
+  }
+  return path.join(cwd, 'artifacts');
+}
+
+function resolveArtifactsDir(value, cwd = process.cwd()) {
+  if (!value) return getDefaultArtifactsDir(cwd);
+  return path.resolve(cwd, value);
+}
+
+module.exports = {
+  getBuildSupportPackageRoot,
+  getWasmRoot,
+  getDefaultArtifactsDir,
+  resolveArtifactsDir
+};

package/src/assemblyscript-compile.js

@@ -0,0 +1,279 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { getDefaultArtifactsDir } = require('./artifacts-dir.js');
+const { spawnSync } = require('node:child_process');
+
+function loadContractsDiagnostics() {
+  try {
+    return require('@pulse-compute/wasm-contracts/diagnostics');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND' && String(error.message).includes('@pulse-compute/wasm-contracts')) {
+      return require('../../contracts/src/diagnostics.js');
+    }
+    throw error;
+  }
+}
+
+const { PACKAGE_VERSION, normalizeArtifact } = loadContractsDiagnostics();
+
+const ASSEMBLYSCRIPT_COMPILE_VERSION = 'pulsewasm.assemblyscript-compile.v1';
+
+const {
+  fileRecord,
+  sha256Text,
+  stripAnsi,
+  truncate
+} = require('./files.js');
+
+function parseAscWarnings(stderr) {
+  const text = stripAnsi(stderr);
+  const warnings = [];
+  const regex = /WARNING\s+(AS\d+):\s+([^\n]+)(?:.|\n)*?in ([^\n]+)\((\d+),(\d+)\)/g;
+  let match;
+  while ((match = regex.exec(text))) {
+    warnings.push({
+      code: match[1],
+      message: match[2].trim(),
+      file: match[3],
+      line: Number(match[4]),
+      column: Number(match[5])
+    });
+  }
+  if (warnings.length === 0 && /WARNING\s+AS\d+:/m.test(text)) {
+    warnings.push({
+      code: 'AS_WARNING',
+      message: 'AssemblyScript emitted one or more warnings. Inspect result.stderr for details.'
+    });
+  }
+  return warnings;
+}
+
+function resolveAssemblyScriptPackageRoot(cwd) {
+  try {
+    const packageJson = require.resolve('assemblyscript/package.json', { paths: [cwd] });
+    return path.dirname(packageJson);
+  } catch (_) {
+    return undefined;
+  }
+}
+
+function resolveAsc(cwd) {
+  const packageRoot = resolveAssemblyScriptPackageRoot(cwd);
+  if (!packageRoot) return undefined;
+  const ascJs = path.join(packageRoot, 'bin', 'asc.js');
+  if (!fs.existsSync(ascJs)) return undefined;
+  return {
+    packageRoot,
+    executable: process.execPath,
+    script: ascJs,
+    display: `node ${path.relative(cwd, ascJs).replace(/\\/g, '/')}`
+  };
+}
+
+function assemblyScriptVersion(cwd) {
+  const packageRoot = resolveAssemblyScriptPackageRoot(cwd);
+  if (!packageRoot) return undefined;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    return pkg.version;
+  } catch (_) {
+    return undefined;
+  }
+}
+
+function writeStagedFiles(stagingDir, shape, core) {
+  const allFiles = [];
+  if (shape && Array.isArray(shape.files)) allFiles.push(...shape.files);
+  if (core && Array.isArray(core.files)) allFiles.push(...core.files);
+
+  // De-duplicate by output path, keeping later/core files when index.as.ts is upgraded by the core generator.
+  const byFile = new Map();
+  for (const file of allFiles) byFile.set(file.file, file.text);
+
+  for (const [file, text] of byFile.entries()) {
+    const abs = path.join(stagingDir, file);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, text, 'utf8');
+  }
+
+  return Array.from(byFile.entries()).map(([file, text]) => ({
+    file,
+    bytes: Buffer.byteLength(text, 'utf8'),
+    sha256: sha256Text(text)
+  }));
+}
+
+function runAscCompile(options) {
+  const cwd = options.cwd || process.cwd();
+  const outDir = options.outDir || getDefaultArtifactsDir(cwd);
+  const shape = options.assemblyScriptShape;
+  const core = options.assemblyScriptCore;
+  const asc = resolveAsc(cwd);
+
+  const diagnostics = [];
+  if (!asc) {
+    diagnostics.push({
+      pass: 'assemblyscript-compile',
+      code: 'PULSEWASM_ASSEMBLYSCRIPT_ASC_MISSING',
+      severity: 'error',
+      message: 'AssemblyScript compiler dependency was not found.',
+      hint: 'Run corepack pnpm install --frozen-lockfile so the assemblyscript devDependency is available, then rerun the compile smoke test.',
+      loc: { file: '<assemblyscript-compile>' }
+    });
+    return { artifact: buildArtifact({ cwd, outDir, status: 'error', diagnostics, shape, core }), diagnostics };
+  }
+
+  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pulsewasm-as-compile-'));
+  const outputDir = path.join(outDir, 'generated', 'as-smoke');
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const stagedFiles = writeStagedFiles(stagingDir, shape, core);
+  const entry = path.join(stagingDir, 'generated/as/index.as.ts');
+  const wasmFile = path.join(outputDir, 'pulsewasm-smoke.wasm');
+  const watFile = path.join(outputDir, 'pulsewasm-smoke.wat');
+
+  const ascArgs = [
+    asc.script,
+    entry,
+    '--outFile', wasmFile,
+    '--textFile', watFile,
+    '--runtime', 'stub',
+    '--noAssert'
+  ];
+
+  const startedAt = Date.now();
+  const proc = spawnSync(asc.executable, ascArgs, {
+    cwd,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024 * 12
+  });
+  const durationMs = Date.now() - startedAt;
+
+  const warnings = parseAscWarnings(proc.stderr);
+
+  if (proc.error) {
+    diagnostics.push({
+      pass: 'assemblyscript-compile',
+      code: 'PULSEWASM_ASSEMBLYSCRIPT_COMPILE_SPAWN_FAILED',
+      severity: 'error',
+      message: `Failed to start AssemblyScript compiler: ${proc.error.message}`,
+      hint: 'Verify Node can execute node_modules/assemblyscript/bin/asc.js.',
+      loc: { file: '<assemblyscript-compile>' }
+    });
+  } else if (proc.status !== 0) {
+    diagnostics.push({
+      pass: 'assemblyscript-compile',
+      code: 'PULSEWASM_ASSEMBLYSCRIPT_COMPILE_FAILED',
+      severity: 'error',
+      message: `AssemblyScript compile smoke test failed with exit code ${proc.status}.`,
+      hint: 'Inspect assemblyscript-compile.json stderr/stdout for asc diagnostics. Generated AS must compile before host binding work.',
+      loc: { file: '<assemblyscript-compile>' },
+      details: {
+        exitCode: proc.status,
+        stderr: truncate(proc.stderr, 8000),
+        stdout: truncate(proc.stdout, 8000)
+      }
+    });
+  }
+
+  const outputs = [];
+  if (fs.existsSync(wasmFile)) outputs.push(fileRecord(wasmFile, cwd, 'wasm-smoke-output'));
+  if (fs.existsSync(watFile)) outputs.push(fileRecord(watFile, cwd, 'wat-smoke-output'));
+
+  const artifact = buildArtifact({
+    cwd,
+    outDir,
+    status: diagnostics.length === 0 ? 'ok' : 'error',
+    diagnostics,
+    warnings,
+    shape,
+    core,
+    asc,
+    assemblyScriptVersion: assemblyScriptVersion(cwd),
+    stagedFiles,
+    outputs,
+    command: {
+      executable: asc.display,
+      args: ascArgs.slice(1).map((arg) => path.isAbsolute(arg) ? path.relative(cwd, arg).replace(/\\/g, '/') : arg)
+    },
+    result: {
+      warnings,
+      exitCode: proc.status,
+      signal: proc.signal,
+      durationMs,
+      stdout: truncate(proc.stdout),
+      stderr: truncate(proc.stderr)
+    }
+  });
+
+  return { artifact, diagnostics, outputFiles: outputs };
+}
+
+function buildArtifact(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  return normalizeArtifact({
+    version: ASSEMBLYSCRIPT_COMPILE_VERSION,
+    generatedBy: options.generatedBy || PACKAGE_VERSION,
+    status: options.status || 'ok',
+    sourceAssemblyScriptShapeVersion: options.shape?.artifact?.version,
+    sourceAssemblyScriptCoreVersion: options.core?.artifact?.version,
+    sourceAssemblyScriptHandlersVersion: options.core?.handlersArtifact?.version,
+    policy: {
+      phase: '9E',
+      sourceOfTruth: 'generated/as/*.as.ts files emitted from validated artifacts',
+      reReadsSource: false,
+      reInfersRouteSemantics: false,
+      compiler: 'assemblyscript asc',
+      compilationOnly: true,
+      wasmExecution: false,
+      hostBindings: false,
+      witBindings: false,
+      purpose: 'prove generated AssemblyScript is syntactically and type valid before local Wasm execution work'
+    },
+    compiler: {
+      package: 'assemblyscript',
+      version: options.assemblyScriptVersion,
+      executable: options.asc?.display
+    },
+    command: options.command,
+    result: options.result,
+    generated: {
+      inputFiles: options.stagedFiles || [],
+      outputFiles: options.outputs || []
+    },
+    diagnostics: options.diagnostics || [],
+    warnings: options.warnings || [],
+    summary: {
+      compiled: options.status === 'ok',
+      inputFiles: (options.stagedFiles || []).length,
+      outputFiles: (options.outputs || []).length,
+      wasmBytes: (options.outputs || []).find((file) => file.kind === 'wasm-smoke-output')?.bytes || 0,
+      watBytes: (options.outputs || []).find((file) => file.kind === 'wat-smoke-output')?.bytes || 0,
+      diagnostics: (options.diagnostics || []).length,
+      warnings: (options.warnings || []).length,
+      wasmExecuted: false,
+      hostBindings: false
+    }
+  }, cwd);
+}
+
+function buildAssemblyScriptCompileSmoke(assemblyScriptShape, assemblyScriptCore, options = {}) {
+  return {
+    version: ASSEMBLYSCRIPT_COMPILE_VERSION,
+    ...runAscCompile({
+      cwd: options.cwd || process.cwd(),
+      outDir: options.outDir,
+      assemblyScriptShape,
+      assemblyScriptCore
+    })
+  };
+}
+
+module.exports = {
+  ASSEMBLYSCRIPT_COMPILE_VERSION,
+  buildAssemblyScriptCompileSmoke,
+  resolveAsc
+};

package/src/files.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function normalizeSlash(value) {
+  return String(value || '').replace(/\\/g, '/');
+}
+
+function sha256Buffer(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+function sha256Text(text) {
+  return crypto.createHash('sha256').update(String(text), 'utf8').digest('hex');
+}
+
+function truncate(value, max = 20000) {
+  const text = String(value || '');
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n... <truncated ${text.length - max} chars>`;
+}
+
+function stripAnsi(value) {
+  return String(value || '').replace(/\u001b\[[0-9;]*m/g, '');
+}
+
+const TEXT_ARTIFACT_EXTENSIONS = new Set([
+  '.cjs', '.js', '.json', '.md', '.mjs', '.toml', '.ts', '.txt', '.wat', '.yaml', '.yml'
+]);
+
+// AssemblyScript and several proof builders use mkdtemp staging directories.
+// Those paths are operational details, not part of the generated program. Keep
+// checked-in/compiler artifacts stable without weakening semantic hash checks.
+function canonicalizeEphemeralPaths(value) {
+  const stagingNames = String(value || '').replace(
+    /pulsewasm-([A-Za-z0-9._-]+?)-[A-Za-z0-9]{6}(?=[^A-Za-z0-9]|$)/g,
+    'pulsewasm-$1-STAGING'
+  );
+  // AssemblyScript writes source names relative to the output directory. That
+  // relative prefix changes when the repository is unpacked at a different
+  // filesystem depth even though the generated program is identical. Remove
+  // only the path leading to a known Pulse staging directory; retain the
+  // staging family and all source-relative suffixes for semantic hashing.
+  return stagingNames
+    .replace(/(?:\.\.\/)+tmp\/(pulsewasm-[A-Za-z0-9._-]+-STAGING)(?=\/)/g, 'tmp/$1')
+    .replace(/\/tmp\/(pulsewasm-[A-Za-z0-9._-]+-STAGING)(?=\/)/g, 'tmp/$1');
+}
+
+function isTextArtifact(filePath) {
+  return TEXT_ARTIFACT_EXTENSIONS.has(path.extname(String(filePath || '')).toLowerCase());
+}
+
+function canonicalizeArtifactBuffer(filePath, buffer) {
+  const source = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer || '');
+  if (!isTextArtifact(filePath)) return source;
+  return Buffer.from(canonicalizeEphemeralPaths(source.toString('utf8')), 'utf8');
+}
+
+function normalizeArtifactFile(filePath) {
+  if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) return false;
+  const before = fs.readFileSync(filePath);
+  const after = canonicalizeArtifactBuffer(filePath, before);
+  if (before.equals(after)) return false;
+  fs.writeFileSync(filePath, after);
+  return true;
+}
+
+function fileRecord(filePath, cwd, kind) {
+  const buffer = fs.readFileSync(filePath);
+  return {
+    file: normalizeSlash(path.relative(cwd, filePath)),
+    kind,
+    bytes: buffer.length,
+    sha256: sha256Buffer(buffer)
+  };
+}
+
+module.exports = {
+  normalizeSlash,
+  sha256Buffer,
+  sha256Text,
+  truncate,
+  stripAnsi,
+  fileRecord,
+  canonicalizeEphemeralPaths,
+  canonicalizeArtifactBuffer,
+  normalizeArtifactFile,
+  isTextArtifact
+};

package/src/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+module.exports = {
+  artifactsDir: require('./artifacts-dir.js'),
+  assemblyscriptCompile: require('./assemblyscript-compile.js'),
+  files: require('./files.js')
+};

package/src/native-optimization.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const {
+  NATIVE_OPTIMIZATION_VERSION,
+  EXPERIMENTAL_NATIVE_SIZE_MODE
+} = require('@pulse-compute/wasm-contracts/project/native-optimization');
+const EXPERIMENTAL_NATIVE_SIZE_OPTIMIZATION = Object.freeze({
+  version: NATIVE_OPTIMIZATION_VERSION,
+  mode: EXPERIMENTAL_NATIVE_SIZE_MODE,
+  experimental: true,
+  goal: 'size',
+  assemblyScript: Object.freeze({
+    optimize: true,
+    optimizeLevel: 3,
+    shrinkLevel: 2,
+    converge: true
+  })
+});
+
+function resolveNativeOptimization(value) {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (
+    value === true
+    || value === EXPERIMENTAL_NATIVE_SIZE_MODE
+    || (typeof value === 'object' && value.mode === EXPERIMENTAL_NATIVE_SIZE_MODE)
+  ) {
+    return EXPERIMENTAL_NATIVE_SIZE_OPTIMIZATION;
+  }
+  throw new TypeError(`Unsupported Pulse Native optimization mode ${String(value && value.mode || value)}.`);
+}
+
+function appendAssemblyScriptOptimizationArgs(args, value) {
+  if (!Array.isArray(args)) throw new TypeError('AssemblyScript optimization arguments require a mutable argument array.');
+  const optimization = resolveNativeOptimization(value);
+  if (!optimization) return undefined;
+  args.push(
+    '--optimizeLevel', String(optimization.assemblyScript.optimizeLevel),
+    '--shrinkLevel', String(optimization.assemblyScript.shrinkLevel)
+  );
+  if (optimization.assemblyScript.converge) args.push('--converge');
+  return optimization;
+}
+
+module.exports = Object.freeze({
+  NATIVE_OPTIMIZATION_VERSION,
+  EXPERIMENTAL_NATIVE_SIZE_MODE,
+  EXPERIMENTAL_NATIVE_SIZE_OPTIMIZATION,
+  resolveNativeOptimization,
+  appendAssemblyScriptOptimizationArgs
+});