sommark 2.3.2 → 3.0.0

package/core/parser.js

@@ -22,10 +22,10 @@ function current_token(tokens, i) {
 
 function validateName(
 	id,
-	keyRegex = /^[a-zA-Z0-9]+$/,
+	keyRegex = /^[a-zA-Z0-9\-_$]+$/,
 	name = "Identifier",
-	rule = "(A–Z, a–z, 0–9)",
-	ruleMessage = "must contain only letters and numbers"
+	rule = "(A–Z, a–z, 0–9, -, _, $)",
+	ruleMessage = "must contain only letters, numbers, hyphens, underscores, or dollar signs ($)"
 ) {
 	if (!keyRegex.test(id)) {
 		parserError([`{line}<$red:Invalid ${name}:$><$blue: '${id}'$>{N}<$yellow:${name} ${ruleMessage}$> <$cyan: ${rule}.$>{line}`]);
@@ -103,12 +103,33 @@ const updateData = (tokens, i) => {
 };
 
 const errorMessage = (tokens, i, expectedValue, behindValue, frontText) => {
-	const tokensUntilError = tokens.slice(0, i);
-	const contextText = tokensUntilError.map(t => t.value).join("");
-	const pointerPadding = " ".repeat(contextText.length);
 	const current = tokens[i] ?? fallback;
+	const errorLineNumber = current.line;
+
+	// Find starting index of the error line
+	let lineStartIndex = i;
+	while (lineStartIndex > 0 && tokens[lineStartIndex - 1].line === errorLineNumber) {
+		lineStartIndex--;
+	}
+
+	// Find ending index of the error line
+	let lineEndIndex = i;
+	while (lineEndIndex < tokens.length - 1 && tokens[lineEndIndex + 1].line === errorLineNumber) {
+		lineEndIndex++;
+	}
+
+	// Get all tokens on the error line
+	const lineTokens = tokens.slice(lineStartIndex, lineEndIndex + 1);
+	const lineContent = lineTokens.map(t => t.value).join('');
+
+	// Get content on the line before the error token
+	const tokensBeforeErrorOnLine = tokens.slice(lineStartIndex, i);
+	const contentBeforeErrorOnLine = tokensBeforeErrorOnLine.map(t => t.value).join('');
+	
+	const pointerPadding = " ".repeat(contentBeforeErrorOnLine.length);
+
 	return [
-		`<$blue:{line}$><$red:Here where error occurred:$>{N}${contextText}${current.value}{N}${pointerPadding}<$yellow:^$>{N}{N}`,
+		`<$blue:{line}$><$red:Here where error occurred:$>{N}${lineContent}{N}${pointerPadding}<$yellow:^$>{N}{N}`,
 		`<$red:${frontText ? frontText : "Expected token"}$> <$blue:'${expectedValue}'$> ${behindValue ? "after <$blue:'" + behindValue + "'$>" : ""} at line <$yellow:${line}$>,`,
 		` from column <$yellow: ${start}$> to <$yellow: ${end}$>`,
 		`{N}<$yellow:Received:$> <$blue:'${value === "\n" ? "\\n' (newline)" : value}'$>`,
@@ -133,12 +154,11 @@ function parseKey(tokens, i) {
 //  Parse Value                                                               //
 // ========================================================================== //
 function parseValue(tokens, i) {
-	let value = current_token(tokens, i).value.trim();
-	// ========================================================================== //
-	//  consume Value                                                             //
-	// ========================================================================== //
+	let val = current_token(tokens, i).value;
+	// consume Value
 	i++;
-	return [value, i];
+	updateData(tokens, i);
+	return [val, i];
 }
 // ========================================================================== //
 //  Parse ','                                                                 //
@@ -222,8 +242,8 @@ function parseBlock(tokens, i) {
 		parserError(errorMessage(tokens, i, block_id, "["));
 	}
 	const id = current_token(tokens, i).value;
-	if (id === end_keyword) {
-		parserError(errorMessage(tokens, i, id, "", `'${id}' is a reserved keyword and cannot be used as an identifier.`));
+	if (id.trim() === end_keyword) {
+		parserError(errorMessage(tokens, i, id, "", `'${id.trim()}' is a reserved keyword and cannot be used as an identifier.`));
 	}
 	blockNode.id = id.trim();
 	validateName(blockNode.id);
@@ -297,6 +317,10 @@ function parseBlock(tokens, i) {
 				}
 
 				if (current_token(tokens, i) && current_token(tokens, i).type === TOKEN_TYPES.COMMA) {
+					v = v.trim();
+					if (v.startsWith('"') && v.endsWith('"')) {
+						v = v.slice(1, -1);
+					}
 					blockNode.args.push(v);
 					if (k) {
 						blockNode.args[k] = v;
@@ -312,6 +336,10 @@ function parseBlock(tokens, i) {
 			}
 		}
 		if (v !== "") {
+			v = v.trim();
+			if (v.startsWith('"') && v.endsWith('"')) {
+				v = v.slice(1, -1);
+			}
 			blockNode.args.push(v);
 			if (k) {
 				blockNode.args[k] = v;
@@ -347,18 +375,17 @@ function parseBlock(tokens, i) {
 			//  consume child node                                                        //
 			// ========================================================================== //
 			i = nextIndex;
-			updateData(tokens, i);
 		} else if (
 			current_token(tokens, i) &&
 			current_token(tokens, i).type === TOKEN_TYPES.OPEN_BRACKET &&
 			peek(tokens, i, 1) &&
-			peek(tokens, i, 1).type === TOKEN_TYPES.END_KEYWORD
+			(peek(tokens, i, 1).type === TOKEN_TYPES.END_KEYWORD || peek(tokens, i, 1).value.trim() === end_keyword)
 		) {
 			// ========================================================================== //
 			//  consume '['                                                               //
 			// ========================================================================== //
 			i++;
-			if (!current_token(tokens, i) || (current_token(tokens, i) && current_token(tokens, i).type !== TOKEN_TYPES.END_KEYWORD)) {
+			if (!current_token(tokens, i) || (current_token(tokens, i) && current_token(tokens, i).type !== TOKEN_TYPES.END_KEYWORD && current_token(tokens, i).value.trim() !== end_keyword)) {
 				parserError(errorMessage(tokens, i, "end", "["));
 			}
 			// ========================================================================== //
@@ -387,7 +414,6 @@ function parseBlock(tokens, i) {
 			}
 			blockNode.body.push(childNode);
 			i = nextIndex;
-			updateData(tokens, i);
 		}
 	}
 	return [blockNode, i];
@@ -402,34 +428,21 @@ function parseInline(tokens, i) {
 	// ========================================================================== //
 	i++;
 	updateData(tokens, i);
-	if (
-		!current_token(tokens, i) ||
-		(current_token(tokens, i) &&
-			current_token(tokens, i).type !== TOKEN_TYPES.VALUE &&
-			current_token(tokens, i).type !== TOKEN_TYPES.ESCAPE)
-	) {
-		parserError(errorMessage(tokens, i, inline_value, "("));
+	if (current_token(tokens, i)) {
+		inlineNode.depth = current_token(tokens, i).depth;
 	}
-	inlineNode.depth = current_token(tokens, i).depth;
-	updateData(tokens, i);
 	while (i < tokens.length) {
-		if (current_token(tokens, i) && current_token(tokens, i).type === TOKEN_TYPES.VALUE) {
-			inlineNode.value += current_token(tokens, i).value;
-			// ========================================================================== //
-			//  consume Inline Value                                                      //
-			// ========================================================================== //
-			i++;
-			continue;
-		} else if (current_token(tokens, i) && current_token(tokens, i).type === TOKEN_TYPES.ESCAPE) {
-			inlineNode.value += current_token(tokens, i).value.slice(1);
-			// ========================================================================== //
-			//  consume Escape Character '\'                                              //
-			// ========================================================================== //
-			i++;
-			continue;
-		} else {
+		const token = current_token(tokens, i);
+		if (!token || token.type === TOKEN_TYPES.CLOSE_PAREN) {
 			break;
 		}
+		if (token.type === TOKEN_TYPES.ESCAPE) {
+			inlineNode.value += token.value.slice(1);
+		} else {
+			inlineNode.value += token.value;
+		}
+		i++;
+		updateData(tokens, i);
 	}
 	if (!current_token(tokens, i) || (current_token(tokens, i) && current_token(tokens, i).type !== TOKEN_TYPES.CLOSE_PAREN)) {
 		parserError(errorMessage(tokens, i, ")", inline_value));
@@ -459,6 +472,9 @@ function parseInline(tokens, i) {
 		parserError(errorMessage(tokens, i, inline_id, "("));
 	}
 	inlineNode.id = current_token(tokens, i).value.trim();
+	if (inlineNode.id === end_keyword) {
+		parserError(errorMessage(tokens, i, inlineNode.id, "", `'${inlineNode.id}' is a reserved keyword and cannot be used as an identifier.`));
+	}
 	validateName(inlineNode.id);
 	// ========================================================================== //
 	//  consume Inline Identifier                                                 //
@@ -478,10 +494,11 @@ function parseInline(tokens, i) {
 		let v = "";
 		const pushArg = () => {
 			if (v !== "") {
-				inlineNode.args.push(v);
-				if (!Number.isInteger(Number(v))) {
-					inlineNode.args[v] = v;
+				v = v.trim();
+				if (v.startsWith('"') && v.endsWith('"')) {
+					v = v.slice(1, -1);
 				}
+				inlineNode.args.push(v);
 				v = "";
 			}
 		};
@@ -560,22 +577,28 @@ function parseInline(tokens, i) {
 // ========================================================================== //
 //  Parse Text                                                                //
 // ========================================================================== //
-function parseText(tokens, i) {
+function parseText(tokens, i, options = {}) {
 	const textNode = makeTextNode();
 	textNode.depth = current_token(tokens, i).depth;
+	const { selectiveUnescape = false } = options;
+
 	while (i < tokens.length) {
-		if (current_token(tokens, i) && current_token(tokens, i).type === TOKEN_TYPES.TEXT) {
-			textNode.text += current_token(tokens, i).value;
-			// ========================================================================== //
-			//  consume Text Node                                                         //
-			// ========================================================================== //
+		const token = current_token(tokens, i);
+		if (token && token.type === TOKEN_TYPES.TEXT) {
+			textNode.text += token.value;
 			i++;
 			updateData(tokens, i);
-		} else if (current_token(tokens, i) && current_token(tokens, i).type === TOKEN_TYPES.ESCAPE) {
-			textNode.text += current_token(tokens, i).value.slice(1);
-			// ========================================================================== //
-			//  consume Text Node                                                         //
-			// ========================================================================== //
+		} else if (token && token.type === TOKEN_TYPES.ESCAPE) {
+			if (selectiveUnescape) {
+				const char = token.value.slice(1);
+				if (char === "@" || char === "_") {
+					textNode.text += char;
+				} else {
+					textNode.text += token.value;
+				}
+			} else {
+				textNode.text += token.value.slice(1); // Standard behavior: unescape all
+			}
 			i++;
 			updateData(tokens, i);
 		} else {
@@ -595,8 +618,8 @@ function parseAtBlock(tokens, i) {
 	i++;
 	updateData(tokens, i);
 	const id = current_token(tokens, i).value;
-	if (id === end_keyword) {
-		parserError(errorMessage(tokens, i, id, "", `'${id}' is a reserved keyword and cannot be used as an identifier.`));
+	if (id.trim() === end_keyword) {
+		parserError(errorMessage(tokens, i, id, "", `'${id.trim()}' is a reserved keyword and cannot be used as an identifier.`));
 	}
 	if (current_token(tokens, i) && current_token(tokens, i).type === TOKEN_TYPES.IDENTIFIER) {
 		atBlockNode.id = id.trim();
@@ -618,21 +641,6 @@ function parseAtBlock(tokens, i) {
 	// ========================================================================== //
 	i++;
 	updateData(tokens, i);
-	if (
-		current_token(tokens, i) &&
-		current_token(tokens, i).type === TOKEN_TYPES.TEXT &&
-		(current_token(tokens, i).value.includes("[") || current_token(tokens, i).value.includes("]"))
-	) {
-		parserError(
-			errorMessage(
-				tokens,
-				i,
-				current_token(tokens, i).value,
-				"",
-				`SomMark uses a scope-based state system to control tokenizing.When @_ is encountered, tokenizing is turned off.Tokenizing is turned back on after the lexer encounters @_end_@. If the At-Block syntax is not completed, all remaining characters are concatenated and treated as plain text until the end of input.`
-			)
-		);
-	}
 	if (current_token(tokens, i) && current_token(tokens, i).type === TOKEN_TYPES.COLON) {
 		// ========================================================================== //
 		//  consume ':'                                                               //
@@ -683,6 +691,10 @@ function parseAtBlock(tokens, i) {
 						break;
 					}
 				}
+				v = v.trim();
+				if (v.startsWith('"') && v.endsWith('"')) {
+					v = v.slice(1, -1);
+				}
 				atBlockNode.args.push(v);
 				if (k) {
 					atBlockNode.args[k] = v;
@@ -698,11 +710,11 @@ function parseAtBlock(tokens, i) {
 				break;
 			}
 		}
-		if (!current_token(tokens, i) || (current_token(tokens, i) && current_token(tokens, i).type !== TOKEN_TYPES.SEMICOLON)) {
-			parserError(errorMessage(tokens, i, ";", at_value));
-		}
-		i = parseSemiColon(tokens, i, at_value);
 	}
+	if (!current_token(tokens, i) || (current_token(tokens, i) && current_token(tokens, i).type !== TOKEN_TYPES.SEMICOLON)) {
+		parserError(errorMessage(tokens, i, ";", at_value));
+	}
+	i = parseSemiColon(tokens, i, at_value);
 	if (
 		!current_token(tokens, i) ||
 		(current_token(tokens, i) &&
@@ -715,7 +727,7 @@ function parseAtBlock(tokens, i) {
 		current_token(tokens, i) &&
 		(current_token(tokens, i).type === TOKEN_TYPES.TEXT || current_token(tokens, i).type === TOKEN_TYPES.ESCAPE)
 	) {
-		const [childNode, nextIndex] = parseText(tokens, i);
+		const [childNode, nextIndex] = parseText(tokens, i, { selectiveUnescape: true });
 		atBlockNode.content = childNode.text;
 		i = nextIndex;
 		updateData(tokens, i);
@@ -728,7 +740,7 @@ function parseAtBlock(tokens, i) {
 	// ========================================================================== //
 	i++;
 	updateData(tokens, i);
-	if (!current_token(tokens, i) || (current_token(tokens, i) && current_token(tokens, i).type !== TOKEN_TYPES.END_KEYWORD)) {
+	if (!current_token(tokens, i) || (current_token(tokens, i) && current_token(tokens, i).type !== TOKEN_TYPES.END_KEYWORD && current_token(tokens, i).value.trim() !== end_keyword)) {
 		parserError(errorMessage(tokens, i, end_keyword, "@_"));
 	}
 	// ========================================================================== //
@@ -775,9 +787,13 @@ function parseNode(tokens, i) {
 		return parseCommentNode(tokens, i);
 	}
 	// ========================================================================== //
-	//  Block                                                                     //
+	//  Block or Reserved Keyword                                                 //
 	// ========================================================================== //
-	else if (current_token(tokens, i).value === "[" && peek(tokens, i, 1) && peek(tokens, i, 1).type !== TOKEN_TYPES.END_KEYWORD) {
+	else if (current_token(tokens, i) && (current_token(tokens, i).type === TOKEN_TYPES.OPEN_BRACKET)) {
+		const next = peek(tokens, i, 1);
+		if (next && (next.type === TOKEN_TYPES.END_KEYWORD || next.value.trim() === end_keyword)) {
+			parserError(errorMessage(tokens, i + 1, "Block ID", "[", `'${next.value.trim()}' is a reserved keyword and cannot be used as a start identifier.`));
+		}
 		return parseBlock(tokens, i);
 	}
 	// ========================================================================== //
@@ -798,7 +814,7 @@ function parseNode(tokens, i) {
 	// ========================================================================== //
 	//  Atblock                                                                   //
 	// ========================================================================== //
-	else if (current_token(tokens, i).value === "@_") {
+	else if (current_token(tokens, i) && (current_token(tokens, i).type === TOKEN_TYPES.OPEN_AT)) {
 		return parseAtBlock(tokens, i);
 	} else {
 		parserError(errorMessage(tokens, i, current_token(tokens, i).value, "", "Syntax Error:"));
@@ -817,8 +833,8 @@ function parser(tokens) {
 	let i = 0;
 	while (i < tokens.length) {
 		let [nodes, nextIndex] = parseNode(tokens, i);
-		if (current_token(tokens, i).type !== TOKEN_TYPES.COMMENT && current_token(tokens, i).depth === 0) {
-			parserError(errorMessage(tokens, i, "[", ""));
+		if (nodes && nodes.type !== "Comment" && nodes.depth === 0) {
+			parserError(errorMessage(tokens, i, "Top-level Block", "", "Top-level content must be wrapped in a block. Found:"));
 		}
 		if (nodes) {
 			ast.push(nodes);

package/core/pluginManager.js

@@ -0,0 +1,139 @@
+export default class PluginManager {
+	constructor(plugins = [], priority = []) {
+		this.plugins = [...plugins].sort((a, b) => {
+			const getIndex = (p) => {
+				// ========================================================================== //
+				// Priority array can contain plugin objects or plugin names (for built-ins)
+				// ========================================================================== //
+				const index = priority.findIndex(item => {
+					if (typeof item === "string") {
+						return item === p.name;
+					}
+					return item === p;
+				});
+				return index;
+			};
+
+			const indexA = getIndex(a);
+			const indexB = getIndex(b);
+
+			// ========================================================================== //
+			// 1. Both have a priority index
+			// ========================================================================== //
+			if (indexA !== -1 && indexB !== -1) {
+				return indexA - indexB;
+			}
+
+			// ========================================================================== //
+			// 2. Only A has a priority
+			// ========================================================================== //
+			if (indexA !== -1) return -1;
+
+			// ========================================================================== //
+			// 3. Only B has a priority
+			// ========================================================================== //
+			if (indexB !== -1) return 1;
+
+			// ========================================================================== //
+			// 4. Neither have a priority
+			// Default rule: built-ins first, then external/user-defined
+			// ========================================================================== //
+			const isBuiltInA = ["module-system", "quote-escaper", "raw-content", "comment-remover", "rules-validation", "sommark-format"].includes(a.name); // Hardcoded for now based on current project
+			const isBuiltInB = ["module-system", "quote-escaper", "raw-content", "comment-remover", "rules-validation", "sommark-format"].includes(b.name);
+
+			if (isBuiltInA && !isBuiltInB) return -1;
+			if (!isBuiltInA && isBuiltInB) return 1;
+
+			return 0;
+		});
+	}
+
+	async runPreprocessor(src, scope) {
+		let processedSrc = src;
+		const preprocessors = this.plugins.filter(p => {
+			const types = Array.isArray(p.type) ? p.type : [p.type];
+			return types.includes("preprocessor") && (p.scope === scope || !p.scope);
+		});
+
+		for (const plugin of preprocessors) {
+			if (typeof plugin.beforeLex === "function") {
+				processedSrc = await plugin.beforeLex.call(plugin, processedSrc);
+			}
+		}
+		return processedSrc;
+	}
+
+	async runAfterLex(tokens) {
+		let processedTokens = tokens;
+		const afterLexers = this.plugins.filter(p => {
+			const types = Array.isArray(p.type) ? p.type : [p.type];
+			return (types.includes("lexer") || types.includes("after-lexer")) && typeof p.afterLex === "function";
+		});
+
+		for (const plugin of afterLexers) {
+			processedTokens = await plugin.afterLex.call(plugin, processedTokens);
+		}
+		return processedTokens;
+	}
+
+	async runOnAst(ast, context = {}) {
+		let processedAst = ast;
+		const astPlugins = this.plugins.filter(p => {
+			const types = Array.isArray(p.type) ? p.type : [p.type];
+			return (types.includes("parser") || types.includes("on-ast")) && typeof p.onAst === "function";
+		});
+
+		for (const plugin of astPlugins) {
+			processedAst = await plugin.onAst.call(plugin, processedAst, context);
+		}
+		return processedAst;
+	}
+
+	getMapperExtensions() {
+		const extensions = { outputs: [], rules: {} };
+		const mapperPlugins = this.plugins.filter(p => {
+			const types = Array.isArray(p.type) ? p.type : [p.type];
+			return types.includes("mapper");
+		});
+
+		for (const plugin of mapperPlugins) {
+			if (plugin.outputs) {
+				extensions.outputs.push(...plugin.outputs);
+			}
+			if (plugin.rules) {
+				extensions.rules = { ...extensions.rules, ...plugin.rules };
+			}
+		}
+		return extensions;
+	}
+
+	runRegisterHooks(sm) {
+		for (const plugin of this.plugins) {
+			const registerFn = plugin.registerOutput || plugin.register;
+			if (typeof registerFn === "function") {
+				registerFn.call(plugin, sm);
+			}
+		}
+	}
+
+	async runTransformers(output) {
+		let processedOutput = output;
+		const transformers = this.plugins.filter(p => {
+			const types = Array.isArray(p.type) ? p.type : [p.type];
+			return types.includes("transform") || types.includes("postprocessor");
+		});
+
+		for (const plugin of transformers) {
+			const transformFn = plugin.transform || plugin.afterTranspile;
+			if (typeof transformFn === "function") {
+				processedOutput = await transformFn.call(plugin, processedOutput);
+			}
+		}
+		return processedOutput;
+	}
+
+	getFormatMapper(formatName) {
+		const plugin = this.plugins.find(p => p.format === formatName && p.mapper);
+		return plugin ? plugin.mapper : null;
+	}
+}

package/core/plugins/comment-remover.js

@@ -0,0 +1,47 @@
+import { COMMENT } from "../labels.js";
+
+/**
+ * Built-in plugin to remove all comments from the AST.
+ * Active by default.
+ */
+export default {
+    name: "comment-remover",
+    type: "on-ast",
+    author: "Adam-Elmi",
+    description: "Removes all comment nodes from the AST during the parsing phase.",
+    onAst: function (ast) {
+        // ========================================================================== //
+        //  Recursive function to filter out comments                               //
+        // ========================================================================== //
+        const cleanNodes = (nodes) => {
+            if (!Array.isArray(nodes)) return nodes;
+
+            return nodes
+                .filter(node => node.type !== COMMENT)
+                .map(node => {
+                    if (node.body && Array.isArray(node.body)) {
+                        return {
+                            ...node,
+                            body: cleanNodes(node.body)
+                        };
+                    }
+                    return node;
+                });
+        };
+        // ========================================================================== //
+        //  Handle both root array and individual node objects                        //
+        // ========================================================================== //
+        if (Array.isArray(ast)) {
+            return cleanNodes(ast);
+        }
+
+        if (ast && ast.body) {
+            return {
+                ...ast,
+                body: cleanNodes(ast.body)
+            };
+        }
+
+        return ast;
+    }
+};

package/core/plugins/module-system.js

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import { runtimeError } from "../errors.js";
+
+const ModuleSystem = {
+	name: "module-system",
+	type: "preprocessor",
+	author: "Adam-Elmi",
+	description: "Provides file inclusion capabilities and global variable substitution (e.g., [[import = ...]]).",
+	scope: "top-level",
+	async beforeLex(src) {
+        if (!src) return src;
+
+        const options = this.options || {};
+        const supportedExtensions = options.supportedExtensions || ["smark", "css", "js"];
+		const importRegex = /\[\[\s*import\s*=\s*\$([a-zA-Z0-9_-]+)\s*:\s*"([^"]+)"\s*\]\]/g;
+		const usageRegex = /\$\[\[([a-zA-Z0-9_-]+)\]\]/g;
+
+        const imports = [];
+        let srcLines = src.split('\n');
+        let processedSrc = src;
+
+        // ========================================================================== //
+        //  0. Module Position Validator & 1. Format Validator                        //
+        // ========================================================================== //
+        const potentialImportRegex = /\[\[\s*import\s*=/;
+        const commentRegex = /^\s*#/;
+        let contentStarted = false;
+        
+        srcLines.forEach((line, index) => {
+            const isImportCandidate = potentialImportRegex.test(line);
+            const isComment = commentRegex.test(line);
+            const isEmpty = line.trim() === "";
+
+            if (isImportCandidate) {
+                if (contentStarted) {
+                    runtimeError([
+                        `<$red:Module Position Error:$> {N}`,
+                        `Import found at line <$yellow:${index + 1}$> after content has already started. {N}`,
+                        `All imports must be at the very top of the file.`
+                    ]);
+                }
+
+                const match = [...line.matchAll(importRegex)][0];
+                if (!match) {
+                    runtimeError([
+                        `<$red:Module Format Error:$> {N}`,
+                        `Invalid import syntax at line <$yellow:${index + 1}$>: <$magenta:${line.trim()}$> {N}`,
+                        `Expected format: <$green:[[import = $key: "path"]]$>`
+                    ]);
+                }
+                
+                const [fullMatch, key, filePath] = match;
+                imports.push({
+                    fullMatch,
+                    key,
+                    path: filePath,
+                    line: index + 1
+                });
+            } else if (!isEmpty && !isComment) {
+                // This is actual content (blocks, text, ...)
+                contentStarted = true;
+            }
+        });
+
+        if (imports.length === 0) return src;
+
+        // ========================================================================== //
+        //  2. Module Path Validator                                                  //
+        // ========================================================================== //
+        imports.forEach(imp => {
+            // Check existence
+            if (!fs.existsSync(imp.path)) {
+                runtimeError([
+                    `<$red:Module Path Error:$> {N}`,
+                    `File not found: <$magenta:${imp.path}$> {N}`,
+                    `Imported at line <$yellow:${imp.line}$> with key <$green:${imp.key}$>`
+                ]);
+            }
+
+            // Check extension
+            const ext = path.extname(imp.path).slice(1);
+            if (!supportedExtensions.includes(ext)) {
+                runtimeError([
+                    `<$red:Module Extension Error:$> {N}`,
+                    `Unsupported extension <$magenta:.${ext}$> for file <$green:${imp.path}$> {N}`,
+                    `Supported extensions: <$cyan:${supportedExtensions.join(", ")}$>`
+                ]);
+            }
+        });
+
+        // ========================================================================== //
+        //  3. Module Usage Validator                                                 //
+        // ========================================================================== //
+        const usageMatches = [...src.matchAll(usageRegex)];
+        const usedKeys = new Set(usageMatches.map(m => m[1]));
+
+        imports.forEach(imp => {
+            if (!usedKeys.has(imp.key)) {
+                runtimeError([
+                    `<$red:Module Usage Error:$> {N}`,
+                    `Module <$green:$${imp.key}$> is imported but never used. {N}`,
+                    `Imported at line <$yellow:${imp.line}$>: <$magenta:${imp.fullMatch}$>`
+                ]);
+            }
+        });
+
+        // ========================================================================== //
+        //  4. Substitution                                                           //
+        // ========================================================================== //
+        // Replace $[[key]] with content
+        for (const match of usageMatches) {
+            const key = match[1];
+            const imp = imports.find(i => i.key === key);
+            if (imp) {
+                try {
+                    const content = await fsPromises.readFile(imp.path, "utf-8");
+                    processedSrc = processedSrc.split(`$[[${key}]]`).join(content);
+                } catch (e) {
+                    runtimeError([`<$red:Module Read Error:$> Failed to read <$magenta:${imp.path}$>`]);
+                }
+            }
+        }
+
+        // ========================================================================== //
+        //  5. Remove the [[import ...]] lines                                       //
+        // ========================================================================== //
+        imports.forEach(imp => {
+            processedSrc = processedSrc.replace(imp.fullMatch, "");
+        });
+
+        return processedSrc;
+	}
+};
+
+export default ModuleSystem;