feat: implement module system foundation (parser + resolver)

build.zig

@@ -41,6 +41,14 @@ pub fn build(b: *std.Build) void {
     parser_module.addImport("ast", ast_module);
     parser_module.addImport("capture_analysis", capture_analysis_module);
 
+    // Create a module for module resolution
+    const module_resolver_module = b.createModule(.{
+        .root_source_file = b.path("src/module_resolver.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    module_resolver_module.addImport("ast", ast_module);
+
     // Create a module for the code generator
     const codegen_module = b.createModule(.{
         .root_source_file = b.path("src/codegen.zig"),
@@ -460,6 +468,29 @@ pub fn build(b: *std.Build) void {
     parser_grammar_tests.root_module.addImport("ast", ast_module);
     parser_grammar_tests.root_module.addImport("parser", parser_module);
 
+    // Module parsing tests
+    const module_parsing_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("test/test_module_parsing.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+        .filters = test_filters,
+    });
+    module_parsing_tests.root_module.addImport("ast", ast_module);
+    module_parsing_tests.root_module.addImport("parser", parser_module);
+
+    // Module resolver tests
+    const module_resolver_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("test/test_module_resolver.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+        .filters = test_filters,
+    });
+    module_resolver_tests.root_module.addImport("module_resolver", module_resolver_module);
+
     // Union type tests
     const union_tests = b.addTest(.{
         .root_module = b.createModule(.{
@@ -512,6 +543,8 @@ pub fn build(b: *std.Build) void {
     const run_parser_basic_tests = b.addRunArtifact(parser_basic_tests);
     const run_parser_dict_literals_tests = b.addRunArtifact(parser_dict_literals_tests);
     const run_parser_grammar_tests = b.addRunArtifact(parser_grammar_tests);
+    const run_module_parsing_tests = b.addRunArtifact(module_parsing_tests);
+    const run_module_resolver_tests = b.addRunArtifact(module_resolver_tests);
     const run_parser_tests = b.addRunArtifact(parser_tests);
     // Note: test filtering must be set via zig test --test-filter, not via build args
     const run_union_tests = b.addRunArtifact(union_tests);
@@ -546,6 +579,8 @@ pub fn build(b: *std.Build) void {
     test_step.dependOn(&run_parser_basic_tests.step);
     test_step.dependOn(&run_parser_dict_literals_tests.step);
     test_step.dependOn(&run_parser_grammar_tests.step);
+    test_step.dependOn(&run_module_parsing_tests.step);
+    test_step.dependOn(&run_module_resolver_tests.step);
     test_step.dependOn(&run_union_tests.step);
     test_step.dependOn(&run_fixture_tests.step);
 

docs/MODULES.md

@@ -0,0 +1,29 @@
+# Shortcake Module System Implementation Guide
+
+**Version**: 0.0.1  
+**Date**: November 16, 2025  
+**Status**: Implementation Specification
+
+This document provides a comprehensive guide for implementing the Shortcake module system, covering parser extensions, AST nodes, symbol resolution, MLIR code generation, and testing strategies.
+
+---
+
+## 1. Overview
+
+The Shortcake module system provides file-based modularity with a simple, explicit import system. Each `.sho` file represents a module, and nested directories map to dotted module names (e.g., `utils/math.sho` → `utils.math`).
+
+### 1.1 Key Features
+
+- **File-based modules**: Each `.sho` file is a module
+- **Dotted names**: `utils/math.sho` becomes `utils.math`
+- **Explicit module declarations**: `mod` keyword marks a file as a module
+- **Default exports**: All declarations are exported by default
+- **Import flexibility**: `import`, `from...import`, and `include` statements
+- **C interop**: Special handling for `$`-prefixed imports
+
+### 1.2 Design Principles
+
+- **Simplicity**: No package managers or complex namespace mechanisms
+- **Explicitness**: All imports are explicit and visible
+- **Predictability**: File layout directly maps to module hierarchy
+- **Performance**: Ahead-of-time compilation with dependency tracking