@chainlink/cre-sdk 1.6.0-alpha.2 → 1.6.0-alpha.3

package/scripts/src/validate-shared.ts

@@ -0,0 +1,400 @@
+/**
+ * Shared utilities for workflow validation modules.
+ *
+ * This module provides common types and functions used by both the runtime
+ * compatibility validator (`validate-workflow-runtime-compat.ts`) and the
+ * determinism warning analyzer (`validate-workflow-determinism.ts`).
+ */
+
+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 or discouraged API is referenced.
+ */
+export 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
+}
+
+/** File extensions treated as scannable source code. */
+export const sourceExtensions = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']
+
+/** Resolves a file path to an absolute path using the current working directory. */
+export const toAbsolutePath = (filePath: string) => path.resolve(filePath)
+
+export const defaultValidationCompilerOptions: ts.CompilerOptions = {
+	allowJs: true,
+	checkJs: true,
+	noEmit: true,
+	skipLibCheck: true,
+	target: ts.ScriptTarget.ESNext,
+	module: ts.ModuleKind.ESNext,
+	moduleResolution: ts.ModuleResolutionKind.Bundler,
+}
+
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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. */
+export 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.
+ */
+export 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.
+ */
+export const getStringLiteralFromCall = (node: ts.CallExpression): string | null => {
+	const [firstArg] = node.arguments
+	if (!firstArg || !ts.isStringLiteral(firstArg)) return null
+	return firstArg.text
+}
+
+/**
+ * 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.
+ */
+export 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
+}
+
+/**
+ * Walks the local import graph starting from `entryFilePath` and collects
+ * all reachable local source files. Also invokes an optional `onModuleSpecifier`
+ * callback for each import specifier found, allowing callers to collect
+ * module-level violations.
+ *
+ * Returns the set of absolute paths to all local source files reachable from
+ * the entry point.
+ */
+export const collectLocalSourceFiles = (
+	entryFilePath: string,
+	onModuleSpecifier?: (
+		specifier: string,
+		pos: number,
+		sourceFile: ts.SourceFile,
+		filePath: string,
+	) => void,
+): Set<string> => {
+	const rootFile = toAbsolutePath(entryFilePath)
+	const filesToScan = [rootFile]
+	const scannedFiles = new Set<string>()
+	const localSourceFiles = new Set<string>()
+
+	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),
+		)
+
+		collectImports(sourceFile, currentFile, (specifier, pos) => {
+			onModuleSpecifier?.(specifier, pos, sourceFile, currentFile)
+
+			if (!isRelativeImport(specifier)) return
+			const resolved = resolveRelativeImport(currentFile, specifier)
+			if (resolved && !scannedFiles.has(resolved)) {
+				filesToScan.push(resolved)
+			}
+		})
+	}
+
+	return localSourceFiles
+}
+
+/**
+ * Walks the AST of a single source file and invokes `onSpecifier` for every
+ * module specifier found in import/export/require/dynamic-import syntax.
+ */
+const collectImports = (
+	sourceFile: ts.SourceFile,
+	filePath: string,
+	onSpecifier: (specifier: string, pos: number) => void,
+) => {
+	const visit = (node: ts.Node) => {
+		// import ... from 'specifier'
+		if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+			onSpecifier(node.moduleSpecifier.text, node.moduleSpecifier.getStart(sourceFile))
+		}
+
+		// export ... from 'specifier'
+		if (
+			ts.isExportDeclaration(node) &&
+			node.moduleSpecifier &&
+			ts.isStringLiteral(node.moduleSpecifier)
+		) {
+			onSpecifier(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)
+		) {
+			onSpecifier(
+				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) {
+					onSpecifier(requiredModule, node.arguments[0].getStart(sourceFile))
+				}
+			}
+
+			// import('specifier')
+			if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+				const importedModule = getStringLiteralFromCall(node)
+				if (importedModule) {
+					onSpecifier(importedModule, node.arguments[0].getStart(sourceFile))
+				}
+			}
+		}
+
+		ts.forEachChild(node, visit)
+	}
+
+	visit(sourceFile)
+}
+
+/**
+ * Creates a TypeScript program from the collected local source files,
+ * merging project compiler options with validation defaults.
+ */
+export const createValidationProgram = (
+	entryFilePath: string,
+	localSourceFiles: Set<string>,
+): ts.Program => {
+	const projectCompilerOptions = loadClosestTsconfigCompilerOptions(entryFilePath) ?? {}
+	return ts.createProgram({
+		rootNames: [...localSourceFiles],
+		options: {
+			...defaultValidationCompilerOptions,
+			...projectCompilerOptions,
+			allowJs: true,
+			checkJs: true,
+			noEmit: true,
+			skipLibCheck: true,
+		},
+	})
+}
+
+/**
+ * Sorts violations by file path, then line, then column, and formats them
+ * as a list of strings with relative paths.
+ */
+export const formatViolations = (violations: Violation[]): string => {
+	const sorted = [...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
+	})
+
+	return sorted
+		.map((violation) => {
+			const relativePath = path.relative(process.cwd(), violation.filePath)
+			return `- ${relativePath}:${violation.line}:${violation.column} ${violation.message}`
+		})
+		.join('\n')
+}