@taqueria/plugin-ligo 0.37.21 → 0.37.34

package/compile.ts

@@ -1,4 +1,13 @@
-import { execCmd, getArch, getArtifactsDir, sendAsyncErr, sendErr, sendJsonRes, sendWarn } from '@taqueria/node-sdk';
+import {
+	execCmd,
+	getArch,
+	getArtifactsDir,
+	sendAsyncErr,
+	sendErr,
+	sendJsonRes,
+	sendRes,
+	sendWarn,
+} from '@taqueria/node-sdk';
 import { access, readFile, writeFile } from 'fs/promises';
 import { basename, extname, join } from 'path';
 import {
@@ -7,34 +16,98 @@ import {
 	getInputFilenameAbsPath,
 	getInputFilenameRelPath,
 	getLigoDockerImage,
+	UnionOpts,
 } from './common';
 
-export type TableRow = { contract: string; artifact: string };
+export type TableRow = { source: string; artifact: string };
 
 export type ExprKind = 'storage' | 'default_storage' | 'parameter';
 
+export type ModuleInfo = {
+	moduleName: string;
+	sourceName: string;
+	sourceFile: string;
+	syntax: 'mligo' | 'jsligo' | 'religo' | 'ligo';
+	type: 'file-main' | 'file-entry' | 'module-main' | 'module-entry';
+};
+
 const COMPILE_ERR_MSG: string = 'Not compiled';
 
 const isStorageKind = (exprKind: ExprKind): boolean => exprKind === 'storage' || exprKind === 'default_storage';
 
-const isLIGOFile = (sourceFile: string): boolean => /.+\.(ligo|religo|mligo|jsligo)$/.test(sourceFile);
+export const isSupportedLigoSyntax = (sourceFile: string) => /\.(mligo|jsligo)$/.test(sourceFile);
+
+export const isUnsupportedLigoSyntax = (sourceFile: string) => /\.(ligo|religo)$/.test(sourceFile);
 
-const isStorageListFile = (sourceFile: string): boolean =>
+export const isLIGOFile = (sourceFile: string) =>
+	isSupportedLigoSyntax(sourceFile) || isUnsupportedLigoSyntax(sourceFile);
+
+export const isStorageListFile = (sourceFile: string): boolean =>
 	/.+\.(storageList|storages)\.(ligo|religo|mligo|jsligo)$/.test(sourceFile);
 
-const isParameterListFile = (sourceFile: string): boolean =>
+export const isParameterListFile = (sourceFile: string): boolean =>
 	/.+\.(parameterList|parameters)\.(ligo|religo|mligo|jsligo)$/.test(sourceFile);
 
-const isContractFile = (sourceFile: string): boolean =>
-	isLIGOFile(sourceFile) && !isStorageListFile(sourceFile) && !isParameterListFile(sourceFile);
-
-const getModuleName = async (parsedArgs: Opts, sourceFile: string): Promise<string | undefined> => {
-	const fileContent = await readFile(getInputFilenameAbsPath(parsedArgs, sourceFile), 'utf8');
-	if (fileContent.includes('@entry') && fileContent.includes('module')) {
-		const match = fileContent.match(/module ([^\s]+)/);
-		return match ? match[1] : undefined;
+export const listContractModules = async (parsedArgs: UnionOpts, sourceFile: string): Promise<ModuleInfo[]> => {
+	try {
+		await getArch();
+		const cmd = await getListDeclarationsCmd(parsedArgs, sourceFile);
+		const { stderr, stdout } = await execCmd(cmd);
+		if (stderr.length > 0) return Promise.reject(stderr);
+
+		return JSON.parse(stdout).declarations.reduce(
+			(acc: ModuleInfo[], decl: string) => {
+				// We need to process delcarations (decl) like so:
+				// 1. If the decl is equal to the string "main", then the module type is "file-main" and the name of the module is the sourceFile.
+				// 2. If the decl is equal to $main, then the module type is "file-entry" and the name fo the module is the sourceFile.
+				// 3. If the decl ends with .main, then the module type is "module-main" and the name of the module is the decl without the .main suffix.
+				// 4. If the decl ends with .$main, then the module type is "module-entry" and the name of the module is the decl without the .$main suffix.
+				// Otherwise, this is not a declaration we care about.
+				const srcFile = removeExt(basename(sourceFile));
+				const syntax = extractExt(sourceFile).replace('.', '');
+
+				if (decl === 'main') {
+					return [...acc, { moduleName: srcFile, sourceName: sourceFile, sourceFile, type: 'file-main', syntax }];
+				} else if (decl === '$main') {
+					return [...acc, { moduleName: srcFile, sourceName: sourceFile, sourceFile, type: 'file-entry', syntax }];
+				} else if (decl.endsWith('.main')) {
+					const moduleName = decl.replace(/\.main$/, '');
+					return [...acc, {
+						moduleName,
+						sourceName: `${sourceFile}/${moduleName}`,
+						sourceFile,
+						type: 'module-main',
+						syntax,
+					}];
+				} else if (decl.endsWith('.$main')) {
+					const moduleName = decl.replace(/\.\$main$/, '');
+					return [...acc, {
+						moduleName,
+						sourceName: `${sourceFile}/${moduleName}`,
+						sourceFile,
+						type: 'module-entry',
+						syntax,
+					}];
+				}
+				return acc;
+			},
+			[],
+		);
+	} catch (err) {
+		emitExternalError(err, sourceFile);
+		return [];
 	}
-	return undefined;
+};
+
+const getListDeclarationsCmd = async (parsedArgs: UnionOpts, sourceFile: string): Promise<string> => {
+	const projectDir = process.env.PROJECT_DIR ?? parsedArgs.projectDir;
+	if (!projectDir) throw new Error(`No project directory provided`);
+	const baseCmd =
+		`DOCKER_DEFAULT_PLATFORM=linux/amd64 docker run --rm -v \"${projectDir}\":/project -w /project -u $(id -u):$(id -g) ${getLigoDockerImage()} info list-declarations`;
+	const inputFile = getInputFilenameRelPath(parsedArgs, sourceFile);
+	const flags = '--display-format json';
+	const cmd = `${baseCmd} ${inputFile} ${flags}`;
+	return cmd;
 };
 
 const extractExt = (path: string): string => {
@@ -49,27 +122,13 @@ const removeExt = (path: string): string => {
 
 const isOutputFormatJSON = (parsedArgs: Opts): boolean => parsedArgs.json;
 
-const getOutputContractFilename = (parsedArgs: Opts, sourceFile: string): string => {
-	const outputFile = basename(sourceFile, extname(sourceFile));
+const getOutputContractFilename = (parsedArgs: Opts, module: ModuleInfo): string => {
 	const ext = isOutputFormatJSON(parsedArgs) ? '.json' : '.tz';
-	return join(getArtifactsDir(parsedArgs), `${outputFile}${ext}`);
+	return join(getArtifactsDir(parsedArgs), `${module.moduleName}${ext}`);
 };
 
-// Get the contract name that the storage/parameter file is associated with
-// e.g. If sourceFile is token.storageList.mligo, then it'll return token.mligo
-const getContractNameForExpr = (sourceFile: string, exprKind: ExprKind): string => {
-	try {
-		return isStorageKind(exprKind)
-			? sourceFile.match(/.+(?=\.(?:storageList|storages)\.(ligo|religo|mligo|jsligo))/)!.join('.')
-			: sourceFile.match(/.+(?=\.(?:parameterList|parameters)\.(ligo|religo|mligo|jsligo))/)!.join('.');
-	} catch (err) {
-		throw new Error(`Something went wrong internally when dealing with filename format: ${err}`);
-	}
-};
-
-// If sourceFile is token.storageList.mligo, then it'll return token.storage.{storageName}.tz
-const getOutputExprFilename = (parsedArgs: Opts, sourceFile: string, exprKind: ExprKind, exprName: string): string => {
-	const contractName = basename(getContractNameForExpr(sourceFile, exprKind), extname(sourceFile));
+const getOutputExprFilename = (parsedArgs: Opts, module: ModuleInfo, exprKind: ExprKind, exprName: string): string => {
+	const contractName = module.moduleName;
 	const ext = isOutputFormatJSON(parsedArgs) ? '.json' : '.tz';
 	const outputFile = exprKind === 'default_storage'
 		? `${contractName}.default_storage${ext}`
@@ -77,78 +136,103 @@ const getOutputExprFilename = (parsedArgs: Opts, sourceFile: string, exprKind: E
 	return join(getArtifactsDir(parsedArgs), `${outputFile}`);
 };
 
-const getCompileContractCmd = async (parsedArgs: Opts, sourceFile: string): Promise<string> => {
+const getCompileContractCmd = async (parsedArgs: Opts, sourceFile: string, module: ModuleInfo): Promise<string> => {
 	const projectDir = process.env.PROJECT_DIR ?? parsedArgs.projectDir;
-	if (!projectDir) throw `No project directory provided`;
+	if (!projectDir) throw new Error(`No project directory provided`);
 	const baseCmd =
 		`DOCKER_DEFAULT_PLATFORM=linux/amd64 docker run --rm -v \"${projectDir}\":/project -w /project -u $(id -u):$(id -g) ${getLigoDockerImage()} compile contract`;
 	const inputFile = getInputFilenameRelPath(parsedArgs, sourceFile);
-	const outputFile = `-o ${getOutputContractFilename(parsedArgs, sourceFile)}`;
+	const outputFile = `-o ${getOutputContractFilename(parsedArgs, module)}`;
 	const flags = isOutputFormatJSON(parsedArgs) ? ' --michelson-format json ' : '';
-	const moduleName = await getModuleName(parsedArgs, sourceFile);
-	const entryFlag = moduleName ? `-m ${moduleName}` : '';
-	const cmd = `${baseCmd} ${inputFile} ${outputFile} ${flags}${entryFlag}`;
+	const moduleFlag = module.type.startsWith('file-') ? '' : `-m ${module.moduleName}`;
+	const cmd = `${baseCmd} ${inputFile} ${outputFile} ${flags}${moduleFlag}`;
 	return cmd;
 };
 
-const getCompileExprCmd = (parsedArgs: Opts, sourceFile: string, exprKind: ExprKind, exprName: string): string => {
+const getCompileExprCmd = (
+	parsedArgs: Opts,
+	sourceFile: string,
+	module: ModuleInfo,
+	exprKind: ExprKind,
+	exprName: string,
+): string => {
 	const projectDir = process.env.PROJECT_DIR ?? parsedArgs.projectDir;
-	if (!projectDir) throw `No project directory provided`;
+	if (!projectDir) throw new Error(`No project directory provided`);
 	const compilerType = isStorageKind(exprKind) ? 'storage' : 'parameter';
 	const baseCmd =
 		`DOCKER_DEFAULT_PLATFORM=linux/amd64 docker run --rm -v \"${projectDir}\":/project -w /project -u $(id -u):$(id -g) ${getLigoDockerImage()} compile ${compilerType}`;
 	const inputFile = getInputFilenameRelPath(parsedArgs, sourceFile);
-	const outputFile = `-o ${getOutputExprFilename(parsedArgs, sourceFile, exprKind, exprName)}`;
+	const outputFile = `-o ${getOutputExprFilename(parsedArgs, module, exprKind, exprName)}`;
 	const flags = isOutputFormatJSON(parsedArgs) ? ' --michelson-format json ' : '';
-	const cmd = `${baseCmd} ${inputFile} ${exprName} ${outputFile} ${flags}`;
+
+	// Parameter and Storage list files are expected to import the smart contract file as the "Contract" module.
+	const moduleFlag = (() => {
+		switch (module.type) {
+			case 'file-main':
+			case 'file-entry':
+				return '-m Contract';
+			default:
+				return `-m Contract.${module.moduleName}`;
+		}
+	})();
+
+	const cmd = `${baseCmd} ${inputFile} ${exprName} ${outputFile} ${flags} ${moduleFlag}`;
 	return cmd;
 };
 
-const compileContract = async (parsedArgs: Opts, sourceFile: string): Promise<TableRow> => {
+const compileContract = async (parsedArgs: Opts, sourceFile: string, module: ModuleInfo): Promise<TableRow> => {
 	try {
 		await getArch();
-		const cmd = await getCompileContractCmd(parsedArgs, sourceFile);
+		const cmd = await getCompileContractCmd(parsedArgs, sourceFile, module);
 		const { stderr } = await execCmd(cmd);
 		if (stderr.length > 0) sendWarn(stderr);
+
 		return {
-			contract: sourceFile,
-			artifact: getOutputContractFilename(parsedArgs, sourceFile),
+			source: module.sourceName,
+			artifact: getOutputContractFilename(parsedArgs, module),
 		};
 	} catch (err) {
 		emitExternalError(err, sourceFile);
 		return {
-			contract: sourceFile,
+			source: module.sourceName,
 			artifact: COMPILE_ERR_MSG,
 		};
 	}
 };
 
-const compileExpr = (parsedArgs: Opts, sourceFile: string, exprKind: ExprKind) =>
-	(exprName: string): Promise<TableRow> =>
-		getArch()
-			.then(() => getCompileExprCmd(parsedArgs, sourceFile, exprKind, exprName))
+const compileExpr =
+	(parsedArgs: Opts, sourceFile: string, module: ModuleInfo, exprKind: ExprKind) =>
+	(exprName: string): Promise<TableRow> => {
+		return getArch()
+			.then(() => getCompileExprCmd(parsedArgs, sourceFile, module, exprKind, exprName))
 			.then(execCmd)
 			.then(({ stderr }) => {
 				if (stderr.length > 0) sendWarn(stderr);
-				const artifactName = getOutputExprFilename(parsedArgs, sourceFile, exprKind, exprName);
+				const artifactName = getOutputExprFilename(parsedArgs, module, exprKind, exprName);
 				return {
-					contract: sourceFile,
+					source: module.sourceName,
 					artifact: artifactName,
 				};
 			})
 			.catch(err => {
 				emitExternalError(err, sourceFile);
 				return {
-					contract: sourceFile,
-					artifact: COMPILE_ERR_MSG,
+					source: module.sourceName,
+					artifact: `${sourceFile} not compiled`,
 				};
 			});
+	};
 
 const getExprNames = (parsedArgs: Opts, sourceFile: string): Promise<string[]> =>
 	readFile(getInputFilenameAbsPath(parsedArgs, sourceFile), 'utf8')
 		.then(data => data.match(/(?<=\n\s*(let|const)\s+)[a-zA-Z0-9_]+/g) ?? []);
 
-const compileExprs = (parsedArgs: Opts, sourceFile: string, exprKind: ExprKind): Promise<TableRow[]> =>
+const compileExprs = (
+	parsedArgs: Opts,
+	sourceFile: string,
+	module: ModuleInfo,
+	exprKind: ExprKind,
+): Promise<TableRow[]> =>
 	getExprNames(parsedArgs, sourceFile)
 		.then(exprNames => {
 			if (exprNames.length === 0) return [];
@@ -156,165 +240,320 @@ const compileExprs = (parsedArgs: Opts, sourceFile: string, exprKind: ExprKind):
 			const restExprNames = exprNames.slice(1, exprNames.length);
 			const firstExprKind = isStorageKind(exprKind) ? 'default_storage' : 'parameter';
 			const restExprKind = isStorageKind(exprKind) ? 'storage' : 'parameter';
-			const firstExprResult = compileExpr(parsedArgs, sourceFile, firstExprKind)(firstExprName);
-			const restExprResults = restExprNames.map(compileExpr(parsedArgs, sourceFile, restExprKind));
+			const firstExprResult = compileExpr(parsedArgs, sourceFile, module, firstExprKind)(firstExprName);
+			const restExprResults = restExprNames.map(compileExpr(parsedArgs, sourceFile, module, restExprKind));
 			return Promise.all([firstExprResult].concat(restExprResults));
 		})
 		.catch(err => {
 			emitExternalError(err, sourceFile);
 			return [{
-				contract: sourceFile,
+				source: module.sourceName,
 				artifact: `No ${isStorageKind(exprKind) ? 'storage' : 'parameter'} expressions compiled`,
 			}];
 		})
 		.then(results =>
 			results.length > 0 ? results : [{
-				contract: sourceFile,
+				source: module.sourceName,
 				artifact: `No ${isStorageKind(exprKind) ? 'storage' : 'parameter'} expressions found`,
 			}]
-		)
-		.then(mergeArtifactsOutput(sourceFile));
-
-// TODO: Just for backwards compatibility. Can be deleted in the future.
-const tryLegacyStorageNamingConvention = (parsedArgs: Opts, sourceFile: string) => {
-	const storageListFile = `${removeExt(sourceFile)}.storages${extractExt(sourceFile)}`;
-	const storageListFilename = getInputFilenameAbsPath(parsedArgs, storageListFile);
-	return access(storageListFilename).then(() => {
-		sendWarn(
-			`Warning: The naming convention of "<CONTRACT>.storages.<EXTENSION>" is deprecated and renamed to "<CONTRACT>.storageList.<EXTENSION>". Please adjust your storage file names accordingly\n`,
-		);
-		return compileExprs(parsedArgs, storageListFile, 'storage');
-	});
-};
-
-// TODO: Just for backwards compatibility. Can be deleted in the future.
-const tryLegacyParameterNamingConvention = (parsedArgs: Opts, sourceFile: string) => {
-	const parameterListFile = `${removeExt(sourceFile)}.parameters${extractExt(sourceFile)}`;
-	const parameterListFilename = getInputFilenameAbsPath(parsedArgs, parameterListFile);
-	return access(parameterListFilename).then(() => {
-		sendWarn(
-			`Warning: The naming convention of "<CONTRACT>.parameters.<EXTENSION>" is deprecated and renamed to "<CONTRACT>.parameterList.<EXTENSION>". Please adjust your parameter file names accordingly\n`,
 		);
-		return compileExprs(parsedArgs, parameterListFile, 'parameter');
-	});
-};
-
-const initContentForStorage = (sourceFile: string): string => {
-	const linkToContract = `#include "${sourceFile}"\n\n`;
 
+const initContentForStorage = (module: ModuleInfo): string => {
+	const linkToContract = `#import "${module.sourceFile}" "Contract"\n\n`;
 	const instruction =
-		'// Define your initial storage values as a list of LIGO variable definitions,\n// the first of which will be considered the default value to be used for origination later on\n';
-
-	const ext = extractExt(sourceFile);
-	let syntax = '';
-	if (ext === '.ligo') syntax = '// E.g. const aStorageValue : aStorageType = 10;\n\n';
-	else if (ext === '.religo') syntax = '// E.g. let aStorageValue : aStorageType = 10;\n\n';
-	else if (ext === '.mligo') syntax = '// E.g. let aStorageValue : aStorageType = 10\n\n';
-	else if (ext === '.jsligo') syntax = '// E.g. const aStorageValue : aStorageType = 10;\n\n';
-
-	return linkToContract + instruction + syntax;
+		'// Define your initial storage values as a list of LIGO variable definitions, the first of which will be considered the default value to be used for origination later on\n';
+
+	const syntax = (() => {
+		const pair = [module.syntax, module.type].join('-');
+		switch (pair) {
+			case 'mligo-file-main':
+				return [
+					'// When this file was created, the smart contract was defined with a main function that was not within a named module. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your storage is a simple value, you can define it directly',
+					'// E.g. let storage = 10',
+					'',
+					'// For added type-safety, you can reference the type of your storage from the contract',
+					'// E.g. let storage : Contract.storage = 10',
+				];
+				break;
+			case 'mligo-file-entry':
+				return [
+					'// When this file was created, the smart contract was defined with an entrypoint using `@entry` that was not within a named module. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your storage is a simple value, you can define it directly',
+					'// E.g. let storage = 10',
+					'',
+					'// For added type-safety, you can reference the type of your storage from the contract',
+					'// E.g. let storage : Contract.storage = 10',
+				];
+				break;
+			case 'mligo-module-main':
+				return [
+					'// When this file was created, the smart contract was defined with a main function that was within a named module. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your storage is a simple value, you can define it directly',
+					'// E.g. let storage = 10',
+					'',
+					'// For added type-safety, you can reference the type of your storage from the contract',
+					`// E.g. let storage : Contract.${module.moduleName}.storage = 10`,
+				];
+				break;
+			case 'mligo-module-entry':
+				return [
+					'// When this file was created, the smart contract was defined with an entrypoint using `@entry` that was within a named module. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your storage is a simple value, you can define it directly',
+					'// E.g. let storage = 10',
+					'',
+					'// For added type-safety, you can reference the type of your storage from the contract',
+					`// E.g. let storage : Contract.${module.moduleName}.storage = 10`,
+				];
+				break;
+			case 'jsligo-file-main':
+				return [
+					'// When this file was created, the smart contract was defined with a main function that was not within a namespace. As such, the examples below are written with that assumption in mind.',
+					`// NOTE: The "storage" type should be exported from the contract file (${module.sourceFile})`,
+					'',
+					'// If your storage is a simple value, you can define it directly',
+					'// E.g. const storage = 10',
+					'',
+					'// For added type-safety, you can reference the type of your storage from the contract. This assumes that you have exported your `storage` type from the contract file.',
+					'// E.g. const storage : Contract.storage = 10',
+				];
+				break;
+			case 'jsligo-file-entry':
+				return [
+					'// When this file was created, the smart contract was defined with an entrypoint using `@entry` that was not within a namespace. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your storage is a simple value, you can define it directly',
+					'// E.g. const storage = 10',
+					'',
+					'// For added type-safety, you can reference the type of your storage from the contract. This assumes that you have exported your `storage` type from the contract file.',
+					'// E.g. const storage : Contract.storage = 10',
+				];
+				break;
+			case 'jsligo-module-main':
+				return [
+					'// When this file was created, the smart contract was defined with a main function that was within a namespace. As such, the examples below are written with that assumption in mind.',
+					`// NOTE: The "storage" type should be exported from the contract file (${module.sourceFile})`,
+					'',
+					'// If your storage is a simple value, you can define it directly',
+					'// E.g. const storage = 10',
+					'',
+					'// For added type-safety, you can reference the type of your storage from the contract. This assumes that you have exported your `storage` type from the contract file.',
+					`// E.g. const storage : Contract.${module.moduleName}.storage = 10`,
+				];
+				break;
+			case 'jsligo-module-entry':
+				return [
+					'// When this file was created, the smart contract was defined with an entrypoint using `@entry` that was within a namespace. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your storage is a simple value, you can define it directly',
+					'// E.g. const storage = 10',
+					'',
+					'// For added type-safety, you can reference the type of your storage from the contract. This assumes that you have exported your `storage` type from the contract file.',
+					`// E.g. const storage : Contract.${module.moduleName}.storage = 10`,
+				];
+				break;
+			default:
+				return [];
+		}
+	})();
+	return linkToContract + instruction + syntax.join('\n');
 };
 
-const initContentForParameter = (sourceFile: string): string => {
-	const linkToContract = `#include "${sourceFile}"\n\n`;
-
+const initContentForParameter = (module: ModuleInfo): string => {
+	const linkToContract = `#import "${module.sourceFile}" "Contract"\n\n`;
 	const instruction = '// Define your parameter values as a list of LIGO variable definitions\n';
 
-	const ext = extractExt(sourceFile);
-	let syntax = '';
-	if (ext === '.ligo') syntax = '// E.g. const aParameterValue : aParameterType = Increment(1);\n\n';
-	else if (ext === '.religo') syntax = '// E.g. let aParameterValue : aParameterType = (Increment (1));\n\n';
-	else if (ext === '.mligo') syntax = '// E.g. let aParameterValue : aParameterType = Increment 1\n\n';
-	else if (ext === '.jsligo') syntax = '// E.g. const aParameterValue : aParameterType = (Increment (1));\n\n';
-
-	return linkToContract + instruction + syntax;
+	const syntax = (() => {
+		const pair = [module.syntax, module.type].join('-');
+		switch (pair) {
+			case 'mligo-file-main':
+				return [
+					'// When this file was created, the smart contract was defined with a main function that was not within a named module. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your parameter is a simple value, you can define it directly',
+					'// E.g. let default_parameter = 10',
+					'',
+					'// For added type-safety, you can reference the type of your parameter from the contract',
+					'// E.g. let default_parameter : Contract.parameter = 10',
+				];
+				break;
+			case 'mligo-file-entry':
+				return [
+					'// When this file was created, the smart contract was defined with an entrypoint using `@entry` that was not within a named module. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your parameter is a simple value, you can define it directly',
+					'// E.g. let default_parameter = 10',
+					'',
+					'// For added type-safety, you can reference the type of your parameter from the contract',
+					'// E.g. let default_parameter : parameter_of Contract = 10',
+				];
+				break;
+			case 'mligo-module-main':
+				return [
+					'// When this file was created, the smart contract was defined with a main function that was within a named module. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your parameter is a simple value, you can define it directly',
+					'// E.g. let default_parameter = 10',
+					'',
+					'// For added type-safety, you can reference the type of your parameter from the contract',
+					`// E.g. let default_parameter : Contract.${module.moduleName}.parameter = 10`,
+				];
+				break;
+			case 'mligo-module-entry':
+				return [
+					'// When this file was created, the smart contract was defined with an entrypoint using `@entry` that was within a named module. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your parameter is a simple value, you can define it directly',
+					'// E.g. let default_parameter = 10',
+					'',
+					'// For added type-safety, you can reference the type of your parameter from the contract',
+					`// E.g. let default_parameter : parameter_of Contract.${module.moduleName} = 10`,
+				];
+				break;
+			case 'jsligo-file-main':
+				return [
+					'// When this file was created, the smart contract was defined with a main function that was not within a namespace. As such, the examples below are written with that assumption in mind.',
+					`// NOTE: The "parameter" type should be exported from the contract file (${module.sourceFile})`,
+					'',
+					'// If your parameter is a simple value, you can define it directly',
+					'// E.g. const default_parameter = 10',
+					'',
+					'// For added type-safety, you can reference the type of your parameter from the contract',
+					'// E.g. const default_parameter : Contract.parameter = 10',
+				];
+				break;
+			case 'jsligo-file-entry':
+				return [
+					'// When this file was created, the smart contract was defined with an entrypoint using `@entry` that was not within a namespace. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your parameter is a simple value, you can define it directly',
+					'// E.g. const default_parameter = 10',
+					'',
+					'// For added type-safety, you can reference the type of your parameter from the contract',
+					'// E.g. const default_parameter : parameter_of Contract = 10',
+				];
+				break;
+			case 'jsligo-module-main':
+				return [
+					'// When this file was created, the smart contract was defined with a main function that was within a namespace. As such, the examples below are written with that assumption in mind.',
+					`// NOTE: The "parameter" type should be exported from the contract file (${module.sourceFile})`,
+					'',
+					'// If your parameter is a simple value, you can define it directly',
+					'// E.g. const default_parameter = 10',
+					'',
+					'// For added type-safety, you can reference the type of your parameter from the contract',
+					`// E.g. const default_parameter : Contract.${module.moduleName}.parameter = 10`,
+				];
+				break;
+			case 'jsligo-module-entry':
+				return [
+					'// When this file was created, the smart contract was defined with an entrypoint using `@entry` that was within a namespace. As such, the examples below are written with that assumption in mind.',
+					'',
+					'// If your parameter is a simple value, you can define it directly',
+					'// E.g. const default_parameter = 10',
+					'',
+					'// For added type-safety, you can reference the type of your parameter from the contract',
+					`// E.g. const default_parameter : parameter_of Contract.${module.moduleName} = 10`,
+				];
+				break;
+			default:
+				return [];
+		}
+	})();
+
+	return linkToContract + instruction + syntax.join('\n');
 };
 
 export const compileContractWithStorageAndParameter = async (
 	parsedArgs: Opts,
 	sourceFile: string,
+	module: ModuleInfo,
 ): Promise<TableRow[]> => {
-	const contractCompileResult = await compileContract(parsedArgs, sourceFile);
+	const contractCompileResult = await compileContract(parsedArgs, sourceFile, module);
 	if (contractCompileResult.artifact === COMPILE_ERR_MSG) return [contractCompileResult];
 
-	const storageListFile = `${removeExt(sourceFile)}.storageList${extractExt(sourceFile)}`;
+	const storageListFile = `${module.moduleName}.storageList${extractExt(sourceFile)}`;
 	const storageListFilename = getInputFilenameAbsPath(parsedArgs, storageListFile);
-	const storageCompileResult = await (access(storageListFilename)
-		.then(() => compileExprs(parsedArgs, storageListFile, 'storage'))
-		.catch(() => tryLegacyStorageNamingConvention(parsedArgs, sourceFile))
+	const storageCompileResult = await access(storageListFilename)
+		.then(() => compileExprs(parsedArgs, storageListFile, module, 'storage'))
 		.catch(() => {
 			sendWarn(
-				`Note: storage file associated with "${sourceFile}" can't be found, so "${storageListFile}" has been created for you. Use this file to define all initial storage values for this contract\n`,
+				`Note: storage file associated with "${module.moduleName}" can't be found, so "${storageListFile}" has been created for you. Use this file to define all initial storage values for this contract\n`,
 			);
-			writeFile(storageListFilename, initContentForStorage(sourceFile), 'utf8');
-		}));
+			return writeFile(storageListFilename, initContentForStorage(module), 'utf8');
+		});
 
-	const parameterListFile = `${removeExt(sourceFile)}.parameterList${extractExt(sourceFile)}`;
+	const parameterListFile = `${module.moduleName}.parameterList${extractExt(sourceFile)}`;
 	const parameterListFilename = getInputFilenameAbsPath(parsedArgs, parameterListFile);
-	const parameterCompileResult = await (access(parameterListFilename)
-		.then(() => compileExprs(parsedArgs, parameterListFile, 'parameter'))
-		.catch(() => tryLegacyParameterNamingConvention(parsedArgs, sourceFile))
+	const parameterCompileResult = await access(parameterListFilename)
+		.then(() => compileExprs(parsedArgs, parameterListFile, module, 'parameter'))
 		.catch(() => {
 			sendWarn(
-				`Note: parameter file associated with "${sourceFile}" can't be found, so "${parameterListFile}" has been created for you. Use this file to define all parameter values for this contract\n`,
+				`Note: parameter file associated with "${module.moduleName}" can't be found, so "${parameterListFile}" has been created for you. Use this file to define all parameter values for this contract\n`,
 			);
-			writeFile(parameterListFilename, initContentForParameter(sourceFile), 'utf8');
-		}));
+			return writeFile(parameterListFilename, initContentForParameter(module), 'utf8');
+		});
 
-	let compileResults: TableRow[] = [contractCompileResult];
-	if (storageCompileResult) compileResults = compileResults.concat(storageCompileResult);
-	if (parameterCompileResult) compileResults = compileResults.concat(parameterCompileResult);
-	return compileResults;
-};
+	const storageArtifacts = storageCompileResult ? storageCompileResult.map(res => res.artifact).join('\n') : '';
+	const parameterArtifacts = parameterCompileResult ? parameterCompileResult.map(res => res.artifact).join('\n') : '';
 
-/*
-Compiling storage/parameter file amounts to compiling multiple expressions in that file,
-resulting in multiple rows with the same file name but different artifact names.
-This will merge these rows into one row with just one mention of the file name.
-e.g.
-┌─────────────────────────┬─────────────────────────────────────────────┐
-│ Contract                │ Artifact                                    │
-├─────────────────────────┼─────────────────────────────────────────────┤
-│ hello.storageList.mligo │ artifacts/hello.default_storage.storage1.tz │
-├─────────────────────────┼─────────────────────────────────────────────┤
-│ hello.storageList.mligo │ artifacts/hello.storage.storage2.tz         │
-└─────────────────────────┴─────────────────────────────────────────────┘
-								versus
-┌─────────────────────────┬─────────────────────────────────────────────┐
-│ Contract                │ Artifact                                    │
-├─────────────────────────┼─────────────────────────────────────────────┤
-│ hello.storageList.mligo │ artifacts/hello.default_storage.storage1.tz │
-│                         │ artifacts/hello.storage.storage2.tz         │
-└─────────────────────────┴─────────────────────────────────────────────┘
-*/
-const mergeArtifactsOutput = (sourceFile: string) =>
-	(tableRows: TableRow[]): TableRow[] => {
-		const artifactsOutput = tableRows.reduce(
-			(acc: string, row: TableRow) => row.artifact === COMPILE_ERR_MSG ? acc : `${acc}${row.artifact}\n`,
-			'',
-		);
-		return [{
-			contract: sourceFile,
-			artifact: artifactsOutput,
-		}];
+	const combinedArtifact = [
+		contractCompileResult.artifact,
+		storageArtifacts,
+		parameterArtifacts,
+	].filter(Boolean).join('\n');
+
+	const combinedRow: TableRow = {
+		source: module.sourceName,
+		artifact: combinedArtifact,
 	};
 
-const compile = (parsedArgs: Opts): Promise<void> => {
-	const sourceFile = parsedArgs.sourceFile!;
-	let p: Promise<TableRow[]>;
-	if (isStorageListFile(sourceFile)) p = compileExprs(parsedArgs, sourceFile, 'storage');
-	else if (isParameterListFile(sourceFile)) p = compileExprs(parsedArgs, sourceFile, 'parameter');
-	else if (isContractFile(sourceFile)) p = compileContractWithStorageAndParameter(parsedArgs, sourceFile);
-	else {
-		return sendAsyncErr(
-			`${sourceFile} doesn't have a valid LIGO extension ('.ligo', '.religo', '.mligo' or '.jsligo')`,
-		);
+	return [combinedRow];
+};
+
+export const compile = async (parsedArgs: Opts): Promise<void> => {
+	const sourceFile = parsedArgs.sourceFile;
+	if (!isLIGOFile(sourceFile)) {
+		sendErr(`${sourceFile} is not a LIGO file`);
+		return;
+	}
+	if (isStorageListFile(sourceFile) || isParameterListFile(sourceFile)) {
+		sendErr(`Storage and parameter list files are not meant to be compiled directly`);
+		return;
+	}
+	if (isUnsupportedLigoSyntax(sourceFile)) {
+		sendErr(`Unsupported LIGO syntax detected in ${sourceFile}. Note, we only support .jsligo and .mligo files.`);
+		return;
+	}
+
+	try {
+		const modules = await listContractModules(parsedArgs, sourceFile);
+		if (modules.length === 0) {
+			return sendJsonRes([
+				{
+					source: sourceFile,
+					artifact: `No contract modules found in "${sourceFile}"`,
+				},
+			]);
+		}
+
+		let allCompileResults: TableRow[] = [];
+		for (const module of modules) {
+			// If we're only to compile a particular module, then we'll skip any that don't match
+			if (parsedArgs.module && parsedArgs.module !== module.moduleName) continue;
+
+			const compileResults = await compileContractWithStorageAndParameter(parsedArgs, sourceFile, module);
+			allCompileResults = allCompileResults.concat(compileResults);
+		}
+
+		sendJsonRes(allCompileResults, { footer: `\nCompiled ${allCompileResults.length} contract(s) in "${sourceFile}"` });
+	} catch (err) {
+		sendErr(`Error processing "${sourceFile}": ${err}`);
 	}
-	return p.then(sendJsonRes).catch(err => sendErr(err, false));
 };
 
 export default compile;
-export const ___TEST___ = {
-	getContractNameForExpr,
-	getOutputExprFilename,
-};