@chainlink/cre-sdk 1.1.4 → 1.2.0

package/scripts/src/validate-workflow-runtime-compat.ts

@@ -0,0 +1,631 @@
+/**
+ * Workflow Runtime Compatibility Validator
+ *
+ * CRE (Compute Runtime Environment) workflows are compiled from TypeScript to
+ * WebAssembly and executed inside a Javy/QuickJS sandbox — NOT a full Node.js
+ * runtime. This means many APIs that developers take for granted (filesystem,
+ * network sockets, crypto, child processes, etc.) are simply not available at
+ * runtime and will silently fail or crash.
+ *
+ * This module performs **static analysis** on workflow source code to catch
+ * these issues at build time, before the workflow is compiled to WASM. It
+ * operates in two passes:
+ *
+ * 1. **Module import analysis** — walks the AST of every reachable source file
+ *    (starting from the workflow entry point) and flags imports from restricted
+ *    Node.js built-in modules (e.g. `node:fs`, `node:crypto`, `node:http`).
+ *    This catches `import`, `export ... from`, `require()`, and dynamic
+ *    `import()` syntax.
+ *
+ * 2. **Global API analysis** — uses the TypeScript type-checker to detect
+ *    references to browser/Node globals that don't exist in QuickJS (e.g.
+ *    `fetch`, `setTimeout`, `window`, `document`). Only flags identifiers
+ *    that resolve to non-local declarations, so user-defined variables with
+ *    the same name (e.g. `const fetch = cre.capabilities.HTTPClient`) are
+ *    not flagged.
+ *
+ * The validator follows relative imports transitively so that violations in
+ * helper files reachable from the entry point are also caught.
+ *
+ * ## How it's used
+ *
+ * This validator runs automatically as part of the `cre-compile` build pipeline:
+ *
+ * ```
+ * cre-compile <path/to/workflow.ts> [path/to/output.wasm]
+ * ```
+ *
+ * The pipeline is: `cre-compile` (CLI) -> `compile-workflow` -> `compile-to-js`
+ * -> **`assertWorkflowRuntimeCompatibility()`** -> bundle -> compile to WASM.
+ *
+ * The validation happens before any bundling or WASM compilation, so developers
+ * get fast, actionable error messages pointing to exact file:line:column
+ * locations instead of cryptic WASM runtime failures.
+ *
+ * ## Layers of protection
+ *
+ * This validator is one of two complementary mechanisms that prevent usage of
+ * unavailable APIs:
+ *
+ * 1. **Compile-time types** (`restricted-apis.d.ts` and `restricted-node-modules.d.ts`)
+ *    — mark restricted APIs as `never` so the TypeScript compiler flags them
+ *    with red squiggles in the IDE. This gives instant feedback while coding.
+ *
+ * 2. **Build-time validation** (this module) — performs AST-level static
+ *    analysis during `cre-compile`. This catches cases that type-level
+ *    restrictions can't cover, such as `require()` calls, dynamic `import()`,
+ *    and usage inside plain `.js` files that don't go through `tsc`.
+ *
+ * @example
+ * ```ts
+ * import { assertWorkflowRuntimeCompatibility } from './validate-workflow-runtime-compat'
+ *
+ * // Throws WorkflowRuntimeCompatibilityError if violations are found
+ * assertWorkflowRuntimeCompatibility('./src/workflow.ts')
+ * ```
+ *
+ * @see https://docs.chain.link/cre/concepts/typescript-wasm-runtime
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import * as ts from 'typescript'
+
+/**
+ * A single detected violation: a location in the source code where a
+ * restricted API is referenced.
+ */
+type Violation = {
+	/** Absolute path to the file containing the violation. */
+	filePath: string
+	/** 1-based line number. */
+	line: number
+	/** 1-based column number. */
+	column: number
+	/** Human-readable description of the violation. */
+	message: string
+}
+
+/**
+ * Node.js built-in module specifiers that are not available in the QuickJS
+ * runtime. Both bare (`fs`) and prefixed (`node:fs`) forms are included
+ * because TypeScript/bundlers accept either.
+ */
+const restrictedModuleSpecifiers = new Set([
+	'crypto',
+	'node:crypto',
+	'fs',
+	'node:fs',
+	'fs/promises',
+	'node:fs/promises',
+	'net',
+	'node:net',
+	'http',
+	'node:http',
+	'https',
+	'node:https',
+	'child_process',
+	'node:child_process',
+	'os',
+	'node:os',
+	'stream',
+	'node:stream',
+	'worker_threads',
+	'node:worker_threads',
+	'dns',
+	'node:dns',
+	'zlib',
+	'node:zlib',
+])
+
+/**
+ * Global identifiers (browser and Node.js) that do not exist in the QuickJS
+ * runtime. For network requests, workflows should use `cre.capabilities.HTTPClient`;
+ * for scheduling, `cre.capabilities.CronCapability`.
+ */
+const restrictedGlobalApis = new Set([
+	'fetch',
+	'window',
+	'document',
+	'XMLHttpRequest',
+	'localStorage',
+	'sessionStorage',
+	'setTimeout',
+	'setInterval',
+])
+
+/** File extensions treated as scannable source code. */
+const sourceExtensions = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']
+
+/**
+ * Error thrown when one or more runtime-incompatible API usages are detected.
+ * The message includes a docs link and a formatted list of every violation
+ * with file path, line, column, and description.
+ */
+class WorkflowRuntimeCompatibilityError extends Error {
+	constructor(violations: Violation[]) {
+		const sortedViolations = [...violations].sort((a, b) => {
+			if (a.filePath !== b.filePath) return a.filePath.localeCompare(b.filePath)
+			if (a.line !== b.line) return a.line - b.line
+			return a.column - b.column
+		})
+
+		const formattedViolations = sortedViolations
+			.map((violation) => {
+				const relativePath = path.relative(process.cwd(), violation.filePath)
+				return `- ${relativePath}:${violation.line}:${violation.column} ${violation.message}`
+			})
+			.join('\n')
+
+		super(
+			`Unsupported API usage found in workflow source.
+CRE workflows run on Javy (QuickJS), not full Node.js.
+Use CRE capabilities instead (for example, HTTPClient instead of fetch/node:http).
+See https://docs.chain.link/cre/concepts/typescript-wasm-runtime
+
+${formattedViolations}`,
+		)
+		this.name = 'WorkflowRuntimeCompatibilityError'
+	}
+}
+
+/** Resolves a file path to an absolute path using the current working directory. */
+const toAbsolutePath = (filePath: string) => path.resolve(filePath)
+
+const defaultValidationCompilerOptions: ts.CompilerOptions = {
+	allowJs: true,
+	checkJs: true,
+	noEmit: true,
+	skipLibCheck: true,
+	target: ts.ScriptTarget.ESNext,
+	module: ts.ModuleKind.ESNext,
+	moduleResolution: ts.ModuleResolutionKind.Bundler,
+}
+
+const formatDiagnostic = (diagnostic: ts.Diagnostic) => {
+	const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')
+	if (!diagnostic.file || diagnostic.start == null) {
+		return message
+	}
+
+	const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start)
+	return `${toAbsolutePath(diagnostic.file.fileName)}:${line + 1}:${character + 1} ${message}`
+}
+
+/**
+ * Loads compiler options from the nearest tsconfig.json so validation runs
+ * against the same ambient/type environment as the workflow project.
+ */
+const loadClosestTsconfigCompilerOptions = (entryFilePath: string): ts.CompilerOptions | null => {
+	const configPath = ts.findConfigFile(
+		path.dirname(entryFilePath),
+		ts.sys.fileExists,
+		'tsconfig.json',
+	)
+	if (!configPath) {
+		return null
+	}
+
+	let unrecoverableDiagnostic: ts.Diagnostic | null = null
+	const parsed = ts.getParsedCommandLineOfConfigFile(
+		configPath,
+		{},
+		{
+			...ts.sys,
+			onUnRecoverableConfigFileDiagnostic: (diagnostic) => {
+				unrecoverableDiagnostic = diagnostic
+			},
+		},
+	)
+
+	if (!parsed) {
+		if (unrecoverableDiagnostic) {
+			throw new Error(
+				`Failed to parse TypeScript config for workflow validation.\n${formatDiagnostic(unrecoverableDiagnostic)}`,
+			)
+		}
+		return null
+	}
+
+	return parsed.options
+}
+
+/**
+ * Maps a file extension to the appropriate TypeScript {@link ts.ScriptKind}
+ * so the parser handles JSX, CommonJS, and ESM files correctly.
+ */
+const getScriptKind = (filePath: string): ts.ScriptKind => {
+	switch (path.extname(filePath).toLowerCase()) {
+		case '.js':
+			return ts.ScriptKind.JS
+		case '.jsx':
+			return ts.ScriptKind.JSX
+		case '.mjs':
+			return ts.ScriptKind.JS
+		case '.cjs':
+			return ts.ScriptKind.JS
+		case '.tsx':
+			return ts.ScriptKind.TSX
+		case '.mts':
+			return ts.ScriptKind.TS
+		case '.cts':
+			return ts.ScriptKind.TS
+		default:
+			return ts.ScriptKind.TS
+	}
+}
+
+/**
+ * Creates a {@link Violation} with 1-based line and column numbers derived
+ * from a character position in the source file.
+ */
+const createViolation = (
+	filePath: string,
+	pos: number,
+	sourceFile: ts.SourceFile,
+	message: string,
+): Violation => {
+	const { line, character } = sourceFile.getLineAndCharacterOfPosition(pos)
+	return {
+		filePath: toAbsolutePath(filePath),
+		line: line + 1,
+		column: character + 1,
+		message,
+	}
+}
+
+/** Returns `true` if the specifier looks like a relative or absolute file path. */
+const isRelativeImport = (specifier: string) => {
+	return specifier.startsWith('./') || specifier.startsWith('../') || specifier.startsWith('/')
+}
+
+/**
+ * Attempts to resolve a relative import specifier to an absolute file path.
+ * Tries the path as-is first, then appends each known source extension, then
+ * looks for an index file inside the directory. Returns `null` if nothing is
+ * found on disk.
+ */
+const resolveRelativeImport = (fromFilePath: string, specifier: string): string | null => {
+	const basePath = specifier.startsWith('/')
+		? path.resolve(specifier)
+		: path.resolve(path.dirname(fromFilePath), specifier)
+
+	if (existsSync(basePath) && statSync(basePath).isFile()) {
+		return toAbsolutePath(basePath)
+	}
+
+	for (const extension of sourceExtensions) {
+		const withExtension = `${basePath}${extension}`
+		if (existsSync(withExtension)) {
+			return toAbsolutePath(withExtension)
+		}
+	}
+
+	for (const extension of sourceExtensions) {
+		const asIndex = path.join(basePath, `index${extension}`)
+		if (existsSync(asIndex)) {
+			return toAbsolutePath(asIndex)
+		}
+	}
+
+	return null
+}
+
+/**
+ * Extracts a string literal from the first argument of a call expression.
+ * Used for `require('node:fs')` and `import('node:fs')` patterns.
+ * Returns `null` if the first argument is not a static string literal.
+ */
+const getStringLiteralFromCall = (node: ts.CallExpression): string | null => {
+	const [firstArg] = node.arguments
+	if (!firstArg || !ts.isStringLiteral(firstArg)) return null
+	return firstArg.text
+}
+
+/**
+ * **Pass 1 — Module import analysis.**
+ *
+ * Walks the AST of a single source file and:
+ * - Flags any import/export/require/dynamic-import of a restricted module.
+ * - Enqueues relative imports for recursive scanning so the validator
+ *   transitively covers the entire local dependency graph.
+ *
+ * Handles all module import syntaxes:
+ * - `import ... from 'node:fs'`
+ * - `export ... from 'node:fs'`
+ * - `import fs = require('node:fs')`
+ * - `require('node:fs')`
+ * - `import('node:fs')`
+ */
+const collectModuleUsage = (
+	sourceFile: ts.SourceFile,
+	filePath: string,
+	violations: Violation[],
+	enqueueFile: (nextFile: string) => void,
+) => {
+	const checkModuleSpecifier = (specifier: string, pos: number) => {
+		if (restrictedModuleSpecifiers.has(specifier)) {
+			violations.push(
+				createViolation(
+					filePath,
+					pos,
+					sourceFile,
+					`'${specifier}' is not available in CRE workflow runtime.`,
+				),
+			)
+		}
+
+		if (!isRelativeImport(specifier)) return
+		const resolved = resolveRelativeImport(filePath, specifier)
+		if (resolved) {
+			enqueueFile(resolved)
+		}
+	}
+
+	const visit = (node: ts.Node) => {
+		// import ... from 'specifier'
+		if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+			checkModuleSpecifier(node.moduleSpecifier.text, node.moduleSpecifier.getStart(sourceFile))
+		}
+
+		// export ... from 'specifier'
+		if (
+			ts.isExportDeclaration(node) &&
+			node.moduleSpecifier &&
+			ts.isStringLiteral(node.moduleSpecifier)
+		) {
+			checkModuleSpecifier(node.moduleSpecifier.text, node.moduleSpecifier.getStart(sourceFile))
+		}
+
+		// import fs = require('specifier')
+		if (
+			ts.isImportEqualsDeclaration(node) &&
+			ts.isExternalModuleReference(node.moduleReference) &&
+			node.moduleReference.expression &&
+			ts.isStringLiteral(node.moduleReference.expression)
+		) {
+			checkModuleSpecifier(
+				node.moduleReference.expression.text,
+				node.moduleReference.expression.getStart(sourceFile),
+			)
+		}
+
+		if (ts.isCallExpression(node)) {
+			// require('specifier')
+			if (ts.isIdentifier(node.expression) && node.expression.text === 'require') {
+				const requiredModule = getStringLiteralFromCall(node)
+				if (requiredModule) {
+					checkModuleSpecifier(requiredModule, node.arguments[0].getStart(sourceFile))
+				}
+			}
+
+			// import('specifier')
+			if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+				const importedModule = getStringLiteralFromCall(node)
+				if (importedModule) {
+					checkModuleSpecifier(importedModule, node.arguments[0].getStart(sourceFile))
+				}
+			}
+		}
+
+		ts.forEachChild(node, visit)
+	}
+
+	visit(sourceFile)
+}
+
+/**
+ * Checks whether an identifier AST node is the **name being declared** (as
+ * opposed to a reference/usage). For example, in `const fetch = ...` the
+ * `fetch` token is a declaration name, while in `fetch(url)` it is a usage.
+ *
+ * This distinction is critical so that user-defined variables that shadow
+ * restricted global names are not flagged as violations.
+ */
+const isDeclarationName = (identifier: ts.Identifier): boolean => {
+	const parent = identifier.parent
+
+	// Variable, function, class, interface, type alias, enum, module,
+	// type parameter, parameter, binding element, import names, enum member,
+	// property/method declarations, property assignments, and labels.
+	if (
+		(ts.isFunctionDeclaration(parent) && parent.name === identifier) ||
+		(ts.isFunctionExpression(parent) && parent.name === identifier) ||
+		(ts.isClassDeclaration(parent) && parent.name === identifier) ||
+		(ts.isClassExpression(parent) && parent.name === identifier) ||
+		(ts.isInterfaceDeclaration(parent) && parent.name === identifier) ||
+		(ts.isTypeAliasDeclaration(parent) && parent.name === identifier) ||
+		(ts.isEnumDeclaration(parent) && parent.name === identifier) ||
+		(ts.isModuleDeclaration(parent) && parent.name === identifier) ||
+		(ts.isTypeParameterDeclaration(parent) && parent.name === identifier) ||
+		(ts.isVariableDeclaration(parent) && parent.name === identifier) ||
+		(ts.isParameter(parent) && parent.name === identifier) ||
+		(ts.isBindingElement(parent) && parent.name === identifier) ||
+		(ts.isImportClause(parent) && parent.name === identifier) ||
+		(ts.isImportSpecifier(parent) && parent.name === identifier) ||
+		(ts.isNamespaceImport(parent) && parent.name === identifier) ||
+		(ts.isImportEqualsDeclaration(parent) && parent.name === identifier) ||
+		(ts.isNamespaceExport(parent) && parent.name === identifier) ||
+		(ts.isEnumMember(parent) && parent.name === identifier) ||
+		(ts.isPropertyDeclaration(parent) && parent.name === identifier) ||
+		(ts.isPropertySignature(parent) && parent.name === identifier) ||
+		(ts.isMethodDeclaration(parent) && parent.name === identifier) ||
+		(ts.isMethodSignature(parent) && parent.name === identifier) ||
+		(ts.isGetAccessorDeclaration(parent) && parent.name === identifier) ||
+		(ts.isSetAccessorDeclaration(parent) && parent.name === identifier) ||
+		(ts.isPropertyAssignment(parent) && parent.name === identifier) ||
+		(ts.isShorthandPropertyAssignment(parent) && parent.name === identifier) ||
+		(ts.isLabeledStatement(parent) && parent.label === identifier)
+	) {
+		return true
+	}
+
+	// Property access (obj.fetch), qualified names (Ns.fetch), and type
+	// references (SomeType) — the right-hand identifier is not a standalone
+	// usage of the global name.
+	if (
+		(ts.isPropertyAccessExpression(parent) && parent.name === identifier) ||
+		(ts.isQualifiedName(parent) && parent.right === identifier) ||
+		(ts.isTypeReferenceNode(parent) && parent.typeName === identifier)
+	) {
+		return true
+	}
+
+	return false
+}
+
+/**
+ * **Pass 2 — Global API analysis.**
+ *
+ * Uses the TypeScript type-checker to find references to restricted global
+ * identifiers (e.g. `fetch`, `setTimeout`, `window`). An identifier is only
+ * flagged if:
+ * - It matches a name in {@link restrictedGlobalApis}.
+ * - It is **not** a declaration name (see {@link isDeclarationName}).
+ * - Its symbol resolves to a declaration outside the local source files,
+ *   meaning it comes from the global scope rather than user code.
+ *
+ * This also catches `globalThis.fetch`-style access patterns.
+ */
+const collectGlobalApiUsage = (
+	program: ts.Program,
+	localSourceFiles: Set<string>,
+	violations: Violation[],
+) => {
+	const checker = program.getTypeChecker()
+
+	for (const sourceFile of program.getSourceFiles()) {
+		const resolvedSourcePath = toAbsolutePath(sourceFile.fileName)
+		if (!localSourceFiles.has(resolvedSourcePath)) continue
+
+		const visit = (node: ts.Node) => {
+			// Direct usage: fetch(...), setTimeout(...)
+			if (
+				ts.isIdentifier(node) &&
+				restrictedGlobalApis.has(node.text) &&
+				!isDeclarationName(node)
+			) {
+				const symbol = checker.getSymbolAtLocation(node)
+				const hasLocalDeclaration =
+					symbol?.declarations?.some((declaration) =>
+						localSourceFiles.has(toAbsolutePath(declaration.getSourceFile().fileName)),
+					) ?? false
+
+				if (!hasLocalDeclaration) {
+					violations.push(
+						createViolation(
+							resolvedSourcePath,
+							node.getStart(sourceFile),
+							sourceFile,
+							`'${node.text}' is not available in CRE workflow runtime.`,
+						),
+					)
+				}
+			}
+
+			// Property access on globalThis: globalThis.fetch(...)
+			if (
+				ts.isPropertyAccessExpression(node) &&
+				ts.isIdentifier(node.expression) &&
+				node.expression.text === 'globalThis' &&
+				restrictedGlobalApis.has(node.name.text)
+			) {
+				violations.push(
+					createViolation(
+						resolvedSourcePath,
+						node.name.getStart(sourceFile),
+						sourceFile,
+						`'globalThis.${node.name.text}' is not available in CRE workflow runtime.`,
+					),
+				)
+			}
+
+			ts.forEachChild(node, visit)
+		}
+
+		visit(sourceFile)
+	}
+}
+
+/**
+ * Validates that a workflow entry file (and all local files it transitively
+ * imports) only uses APIs available in the CRE QuickJS/WASM runtime.
+ *
+ * The check runs in two passes:
+ *
+ * 1. **Module import scan** — starting from `entryFilePath`, recursively
+ *    parses every reachable local source file and flags imports from
+ *    restricted Node.js built-in modules.
+ *
+ * 2. **Global API scan** — creates a TypeScript program from the collected
+ *    source files and uses the type-checker to flag references to restricted
+ *    global identifiers that resolve to non-local (i.e. global) declarations.
+ *
+ * @param entryFilePath - Path to the workflow entry file (absolute or relative).
+ * @throws {WorkflowRuntimeCompatibilityError} If any violations are found.
+ *   The error message includes a link to the CRE runtime docs and a formatted
+ *   list of every violation with file:line:column and description.
+ *
+ * @example
+ * ```ts
+ * // During the cre-compile build step:
+ * assertWorkflowRuntimeCompatibility('./src/workflow.ts')
+ * // Throws if the workflow (or any file it imports) uses fetch, node:fs, etc.
+ * ```
+ *
+ * @see https://docs.chain.link/cre/concepts/typescript-wasm-runtime
+ */
+export const assertWorkflowRuntimeCompatibility = (entryFilePath: string) => {
+	const rootFile = toAbsolutePath(entryFilePath)
+	const projectCompilerOptions = loadClosestTsconfigCompilerOptions(rootFile) ?? {}
+	const filesToScan = [rootFile]
+	const scannedFiles = new Set<string>()
+	const localSourceFiles = new Set<string>()
+	const violations: Violation[] = []
+
+	// Pass 1: Walk the local import graph and collect module-level violations.
+	while (filesToScan.length > 0) {
+		const currentFile = filesToScan.pop()
+		if (!currentFile || scannedFiles.has(currentFile)) continue
+		scannedFiles.add(currentFile)
+
+		if (!existsSync(currentFile)) continue
+		localSourceFiles.add(currentFile)
+
+		const fileContents = readFileSync(currentFile, 'utf-8')
+		const sourceFile = ts.createSourceFile(
+			currentFile,
+			fileContents,
+			ts.ScriptTarget.Latest,
+			true,
+			getScriptKind(currentFile),
+		)
+
+		collectModuleUsage(sourceFile, currentFile, violations, (nextFile) => {
+			if (!scannedFiles.has(nextFile)) {
+				filesToScan.push(nextFile)
+			}
+		})
+	}
+
+	// Pass 2: Use the type-checker to detect restricted global API usage.
+	const program = ts.createProgram({
+		rootNames: [...localSourceFiles],
+		options: {
+			...defaultValidationCompilerOptions,
+			...projectCompilerOptions,
+			allowJs: true,
+			checkJs: true,
+			noEmit: true,
+			skipLibCheck: true,
+		},
+	})
+
+	collectGlobalApiUsage(program, localSourceFiles, violations)
+
+	if (violations.length > 0) {
+		throw new WorkflowRuntimeCompatibilityError(violations)
+	}
+}
+
+export { WorkflowRuntimeCompatibilityError }