Fail closed on file-backed imports before codegen

Author: code5717

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- File-backed local imports now fail closed before backend codegen, and docs
+  now distinguish resolver validation from unsupported multi-file linking.
 - Tightened runnable examples so conditionals, callbacks, and state-machine
   demos exercise their documented branches in both native backends.
 - `examples/014_generics.a7` now runs real generic functions and generic struct

MISSING_FEATURES.md

@@ -28,7 +28,7 @@
 14. Installed CLI entrypoint (`a7`) is wired through `pyproject.toml`.
 15. Debug/release example artifact verification is available through `scripts/build_examples.py`.
 16. `run_all_tests.sh` includes C backend verification, both example E2E verifiers, selected Zig/C parity smoke checks, debug/release artifact builds, the error-stage matrix, docs style checks, and full pytest.
-17. Local file-based imports now fail closed during semantic analysis instead of swallowing module loading failures.
+17. Local file-based imports now fail closed during codegen modes instead of emitting unresolved backend code. Semantic mode still validates resolver loading.
 18. Zig unsupported expression fallbacks now fail as compiler-side codegen errors instead of generated `@compileError` expressions.
 19. `fall` now lowers in both Zig and C when used as the final direct
     statement of a non-final match case.
@@ -98,6 +98,7 @@
 
 6. **Module-system parity**
    - Missing or broken local imports now fail closed.
+   - Existing file-backed local imports resolve for semantic validation but are rejected before backend codegen until multi-file lowering/linking exists.
    - Built-in stdlib imports are virtual modules, but now participate in `ModuleResolver`/`ModuleTable` symbol registration like file-based modules.
    - `std/string`, `std/mem`, and `std/collections` are planned but not current public stdlib modules.
 

README.md

@@ -165,7 +165,7 @@ Use fixed-width integers such as `i32`, `i64`, `u32`, or `u64` when the data its
 - **Function Rules**: Direct and mutual recursion are semantic errors
 - **Expressions**: All operators with proper precedence, casts, if-expressions, struct/array literals, untagged union field literals/access
 - **Memory**: Property-based pointer syntax (`.adr`, `.val`), scalar/struct `new` and `del`, defer cleanup. Heap fixed arrays (`new [N]T`) are rejected until the language model is defined.
-- **Imports**: Module system with named imports, using imports, aliased imports
+- **Imports**: Virtual `std/io` and `std/math` modules with aliases; file-backed local imports resolve for validation but fail closed before backend codegen until module linking is implemented
 - **Generics**: Type parameters (`$T`), constraints, type sets, generic structs, generic struct literals, and simple top-level generic function calls in both backends
 - **Code Generation**: A7 → Zig and A7 → C backends
 - **Standard Library**: Registry with io and math modules, backend-specific mappings

TODO.md

@@ -169,7 +169,7 @@ Features that are spec'd and partially implemented, or missing from one backend.
 
 - [x] Stop treating import/module loading as best-effort.
   Files: `a7/compile.py`, `a7/module_resolver.py`
-  Notes: fixed for local file-based imports; missing or broken dependencies now fail as semantic errors while virtual stdlib imports remain supported.
+  Notes: missing or broken dependencies now fail as semantic errors while virtual stdlib imports remain supported. Existing file-backed imports are resolver-validated in semantic mode and fail closed before backend codegen until module linking exists.
 
 - [x] Unify built-in stdlib imports with file-based module resolution.
   Files: `a7/module_resolver.py`, `a7/passes/name_resolution.py`, `a7/stdlib/__init__.py`

a7/compile.py

@@ -19,9 +19,10 @@
 
 from rich.console import Console
 
+from .ast_nodes import ASTNode, NodeKind
 from .ast_preprocessor import ASTPreprocessor
 from .backends import get_backend
-from .errors import CompilerError, ParseError, SemanticError, display_error, display_errors
+from .errors import CompilerError, ParseError, SemanticError, SemanticErrorType, display_error, display_errors
 from .formatters import ConsoleFormatter, JSONFormatter, MarkdownFormatter
 from .parser import Parser
 from .passes import GenericLoweringPass, NameResolutionPass, SemanticValidationPass, TypeCheckingPass
@@ -238,12 +239,22 @@ def compile_file_detailed(
                     module_resolver.load_program_dependencies(ast, str(input_path))
                 except SemanticError as e:
                     import_errors.append(e)
+                backend_import_errors: list[Any] = []
+                codegen_modes = {CompileMode.COMPILE, CompileMode.PIPELINE, CompileMode.DOC}
+                if not import_errors and self.mode in codegen_modes:
+                    backend_import_errors = self._backend_unsupported_import_errors(
+                        ast=ast,
+                        module_resolver=module_resolver,
+                        filename=str(input_path),
+                        source_lines=source_lines,
+                    )
 
                 name_resolver = NameResolutionPass()
                 name_resolver.source_lines = source_lines
                 symbol_table = name_resolver.analyze(ast, str(input_path))
                 nr_ok = len(name_resolver.errors) == 0
                 import_ok = len(import_errors) == 0
+                backend_import_ok = len(backend_import_errors) == 0
                 semantic_passes.append(
                     {
                         "name": "Import Resolution",
@@ -253,6 +264,15 @@ def compile_file_detailed(
                 )
                 if import_errors:
                     all_errors.extend(import_errors)
+                semantic_passes.append(
+                    {
+                        "name": "Backend Import Support",
+                        "ok": backend_import_ok,
+                        "errors": len(backend_import_errors),
+                    }
+                )
+                if backend_import_errors:
+                    all_errors.extend(backend_import_errors)
                 semantic_passes.append(
                     {
                         "name": "Name Resolution",
@@ -263,7 +283,7 @@ def compile_file_detailed(
                 if name_resolver.errors:
                     all_errors.extend(name_resolver.errors)
 
-                if import_ok and nr_ok:
+                if import_ok and backend_import_ok and nr_ok:
                     type_checker = TypeCheckingPass(symbol_table)
                     type_checker.source_lines = source_lines
                     type_checker.analyze(ast, str(input_path))
@@ -479,6 +499,39 @@ def _emit_success(self, result: CompilationResult) -> None:
         if result.doc_path:
             console.print(f"[blue]📄[/blue] Documentation written to {result.doc_path}")
 
+    def _backend_unsupported_import_errors(
+        self,
+        *,
+        ast: ASTNode,
+        module_resolver: Any,
+        filename: str,
+        source_lines: list[str],
+    ) -> list[SemanticError]:
+        """Reject file-backed modules until codegen can lower/link their symbols."""
+        if ast.kind != NodeKind.PROGRAM:
+            return []
+
+        errors: list[SemanticError] = []
+        for decl in ast.declarations or []:
+            if decl.kind != NodeKind.IMPORT:
+                continue
+            module_path = decl.module_path or ""
+            if module_resolver.is_virtual_module(module_path):
+                continue
+            errors.append(
+                SemanticError.from_type(
+                    SemanticErrorType.UNSUPPORTED_IMPORT,
+                    span=decl.span,
+                    filename=filename,
+                    source_lines=source_lines,
+                    custom_message=(
+                        f"File-backed import '{module_path}' resolves, but {self.backend} "
+                        "backend lowering/linking for local modules is not implemented yet"
+                    ),
+                )
+            )
+        return errors
+
     def _finish_with_failure(
         self,
         result: CompilationResult,

a7/errors.py

@@ -87,6 +87,7 @@ class SemanticErrorType(Enum):
     CIRCULAR_IMPORT = "circular_import"
     MODULE_NOT_FOUND = "module_not_found"
     IMPORT_NAME_CONFLICT = "import_name_conflict"
+    UNSUPPORTED_IMPORT = "unsupported_import"
 
     # Generic errors
     GENERIC_PARAM_MISMATCH = "generic_param_mismatch"
@@ -244,6 +245,7 @@ def get_semantic_error_message(error_type: SemanticErrorType) -> str:
         SemanticErrorType.CIRCULAR_IMPORT: "Circular import detected",
         SemanticErrorType.MODULE_NOT_FOUND: "Module not found",
         SemanticErrorType.IMPORT_NAME_CONFLICT: "Import name conflicts with existing definition",
+        SemanticErrorType.UNSUPPORTED_IMPORT: "Unsupported import",
 
         # Generic errors
         SemanticErrorType.GENERIC_PARAM_MISMATCH: "Generic parameter count mismatch",
@@ -293,6 +295,7 @@ def get_semantic_error_advice(error_type: SemanticErrorType) -> str:
         SemanticErrorType.CIRCULAR_IMPORT: "Reorganize modules to remove circular dependencies",
         SemanticErrorType.MODULE_NOT_FOUND: "Check the module path and ensure the file exists",
         SemanticErrorType.IMPORT_NAME_CONFLICT: "Use an alias for the import or rename the conflicting definition",
+        SemanticErrorType.UNSUPPORTED_IMPORT: "Use a current virtual stdlib import or keep file-backed modules in the same source file until backend linking is implemented",
 
         # Generic errors
         SemanticErrorType.GENERIC_PARAM_MISMATCH: "Provide the correct number of generic type arguments",

docs/SPEC.md

@@ -1420,9 +1420,12 @@ integrate_2d :: fn(f: fn(f64, f64) f64, bounds: [4]f64, steps: [2]usize) f64 {
 
 ## 10. Modules and Visibility
 
-### 10.1 File-Based Module System
+### 10.1 File-Based Module Model
 
 Every A7 source file is a module. There is no explicit `module` keyword.
+Current backend codegen does not link multiple `.a7` files yet; file-backed
+imports resolve during semantic validation but are rejected before Zig/C
+emission.
 
 ```a7
 // File: vector.a7
@@ -1452,26 +1455,21 @@ normalize :: fn(v: ref Vec3) {
 ### 10.2 Import Statements
 
 ```a7
-// Import by filename (without .a7 extension)
-math :: import "math"
-io :: import "io"
+// Current backend-lowered virtual stdlib imports
+math :: import "std/math"
+io :: import "std/io"
 
-// Import user library
-mylib :: import "mylib"
+// Aliases are supported for virtual stdlib imports
+console :: import "std/io"
 
-// Import with alias
-vec :: import "vector"
-
-// Import specific items
+// Parsed/resolver forms for file-backed modules
 import "vector" { Vec3, dot }
-
-// Import all public items
 using import "vector"
-
-// Relative imports
 sibling :: import "./sibling"
-parent :: import "../utils"
 subfolder :: import "subfolder/helper"
+
+// Parent traversal imports are rejected by the resolver
+parent :: import "../utils"  // error
 ```
 
 ### 10.3 Standard Library Status
@@ -1483,7 +1481,10 @@ Current implementation:
 - Virtual stdlib modules are registered through the module resolver and may be
   imported with arbitrary local aliases, for example
   `console :: import "std/io"`.
-- Local file imports such as `./vector` resolve from on-disk `.a7` files.
+- Local file imports such as `./vector` can resolve from on-disk `.a7` files
+  during semantic validation, but backend lowering/linking for file-backed
+  modules is not implemented yet. Compile/pipeline/doc modes reject them before
+  codegen instead of emitting invalid Zig/C.
 
 Planned, not implemented as public stdlib modules yet:
 

site/public/docs/features.md

@@ -3,7 +3,7 @@
 ## Language
 
 - Static typing with inference in supported contexts.
-- Functions, structs, enums, untagged union field literals/access, aliases, modules, and generics.
+- Functions, structs, enums, untagged union field literals/access, aliases, virtual stdlib modules, and generics.
 - Simple top-level generic function calls, type-set constraints, and used generic struct instances lower in both Zig and C backends.
 - `if`, `while`, `for`, `for-in`, `match`, labeled loops, `break`, and `continue`.
 - Arrays, slices, string slices, pointers, references, and manual `new` / `del`.
@@ -28,4 +28,4 @@
 
 ## Current Limits
 
-The status page is canonical for remaining gaps. Key limits include complete memory/lifetime guarantees, broader generic propagation beyond current function and struct instance coverage, parsed-only variadic declarations, reserved-but-unimplemented intrinsics beyond `@type_set(...)`, tagged union workflows, and arbitrary symbolic inequality reasoning.
+The status page is canonical for remaining gaps. Key limits include complete memory/lifetime guarantees, backend lowering/linking for file-backed local modules, broader generic propagation beyond current function and struct instance coverage, parsed-only variadic declarations, reserved-but-unimplemented intrinsics beyond `@type_set(...)`, tagged union workflows, and arbitrary symbolic inequality reasoning.

site/public/docs/guide/features.md

@@ -3,7 +3,7 @@
 ## Language
 
 - Static typing with inference in supported contexts.
-- Functions, structs, enums, untagged union field literals/access, aliases, modules, and generics.
+- Functions, structs, enums, untagged union field literals/access, aliases, virtual stdlib modules, and generics.
 - Simple top-level generic function calls and used generic struct instances lower in both Zig and C backends.
 - `if`, `while`, `for`, `for-in`, `match`, labeled loops, `break`, and `continue`.
 - Arrays, slices, string slices, pointers, references, and manual `new` / `del`.
@@ -28,4 +28,4 @@
 
 ## Current Limits
 
-The status page is canonical for remaining gaps. Key limits include complete memory/lifetime guarantees, broader generic propagation beyond current function and struct instance coverage, tagged union workflows, and arbitrary symbolic inequality reasoning.
+The status page is canonical for remaining gaps. Key limits include complete memory/lifetime guarantees, backend lowering/linking for file-backed local modules, broader generic propagation beyond current function and struct instance coverage, tagged union workflows, and arbitrary symbolic inequality reasoning.

site/public/docs/language.md

@@ -51,6 +51,11 @@ These modules are virtual built-ins registered through the module resolver, so
 local aliases such as `console :: import "std/io"` and
 `mathlib :: import "std/math"` lower the same way as `io` and `math`.
 
+File-backed local imports can be resolved during semantic validation, but
+Zig/C backend lowering and linking for multiple `.a7` files is not implemented
+yet. Compile, pipeline, and doc modes reject file-backed imports before codegen
+instead of emitting unresolved target code.
+
 Source stubs such as `mem` and `string` exist in the repository but are not registered public stdlib modules yet.
 
 ## Current Syntax Limits