feat: add C backend and improve compiler validation

Author: code5717

CHANGELOG.md

@@ -39,6 +39,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Populated by preprocessor, read by backends
 
 ### Changed
+- **Language Documentation Completion (Site)**
+  - Expanded `site/src/pages/Language.tsx` into a full reference covering lexical rules, literals, declarations, expressions, control flow, functions, memory, generics, modules, intrinsics, operators, and grammar quick-reference.
+  - Added explicit implementation-state callouts linking language docs to current semantic gaps tracked in `MISSING_FEATURES.md` / site status.
+
 - **Current Test Baseline**
   - `PYTHONPATH=. uv run pytest` now reports `1039 passed, 7 failed, 0 skipped`.
   - Remaining failures are documented in `MISSING_FEATURES.md` and mirrored in docs/site status pages.

MISSING_FEATURES.md

@@ -1,63 +1,47 @@
-# A7 Compiler — Missing Features Snapshot
+# A7 Compiler — Language-Core Gap Snapshot
 
-**Compiler Status**: Full pipeline runs (Tokenizer → Parser → Semantic → Preprocessor → Zig Codegen).  
-**Current Test Status** (`PYTHONPATH=. uv run pytest`, 2026-02-21): **1039 passed, 7 failed, 0 skipped**.  
+**Compiler Status**: Full pipeline runs (Tokenizer -> Parser -> Semantic -> Preprocessor -> Codegen).  
+**Current Test Status** (`PYTHONPATH=. uv run pytest -q`, 2026-02-24): **1067 passed, 0 failed, 0 skipped**.  
 **Examples**: 36/36 pass end-to-end compile + build + run + output verification.
 
 ---
 
-## Newly Unskipped Semantic Gaps
-
-The 9 previously skipped semantic tests were unskipped. Two now pass; seven fail and define the current missing work. Those failures collapse into six implementation areas below.
-
-1. **Match expressions are parsed but not type-checked**
-   - Failing test: `test/test_semantic_control_flow.py:434`
-   - Current error: `Unknown expression kind: NodeKind.MATCH_EXPR`
-   - Needed:
-     - Add `MATCH_EXPR` handling in `TypeCheckingPass._visit_expression_impl`.
-     - Type-check each case arm expression and `else` expression.
-     - Enforce arm type compatibility and return unified expression type.
-
-2. **`@type_set(...)` in value context does not parse correctly**
-   - Failing test: `test/test_semantic_generics.py:159`
-   - Current error: `Expected expression` at first type argument token (`i8`).
-   - Needed:
-     - Treat `@type_set` as a type-taking builtin when parsed as expression, or
-     - Parse `@type_set(...)` declarations through a dedicated type-set declaration path.
-
-3. **Generic arithmetic in function bodies is too strict without constraint flow**
-   - Failing test: `test/test_semantic_generics.py:176`
-   - Current error: `Requires numeric type` for `$T * 2`.
-   - Needed:
-     - Propagate generic constraints (or inferred concrete type bindings) into expression checking.
-     - Allow arithmetic when `$T` is known numeric by constraint or call-site inference.
-
-4. **Generic struct literal field checks do not substitute type arguments**
-   - Failing test: `test/test_semantic_generics.py:248`
-   - Current error: `Type mismatch: expected '$T', got 'i32'`.
-   - Needed:
-     - Instantiate/substitute struct field types for `Pair(i32, string){...}` before field validation.
-
-5. **Field access on generic struct instances is unresolved**
-   - Failing tests:
-     - `test/test_semantic_generics.py:263`
-     - `test/test_semantic_generics.py:434`
-   - Current error: `Cannot access field on non-struct type: got 'Box(i32)'` / `Node(i32)`.
-   - Needed:
-     - Resolve `GenericInstanceType` to concrete `StructType` during field access.
-     - Support recursive generic instantiation safely (cycle-aware resolution for recursive types).
-
-6. **Literal initialization for generic locals lacks inference/coercion**
-   - Failing test: `test/test_semantic_generics.py:311`
-   - Current error: `Type mismatch: expected '$T', got 'i32'` for `total: $T = 0`.
-   - Needed:
-     - Permit numeric literal initialization for generic numeric variables, or
-     - Specialize generic function body typing from call-site type mapping before local checks.
+## Recently Completed (Language Core)
+
+1. `match` expressions are type-checked and participate in expression typing.
+2. `@type_set(...)` parses in value context.
+3. Generic arithmetic and generic local literal initialization are relaxed where valid.
+4. Generic struct literal field checks substitute concrete type arguments.
+5. Field access resolves concrete struct layout for generic instances.
+6. Match semantics now enforce:
+   - pattern type compatibility with the scrutinee,
+   - bool/enum exhaustiveness (or explicit `else` / wildcard),
+   - wildcard pattern parsing (`case _:`),
+   - return-path correctness for exhaustive enum/bool `match` without `else`.
+
+---
+
+## Remaining Language-First Gaps
+
+1. **`fall` statement semantics**
+   - `fall` is parsed (`NodeKind.FALL`) but not yet validated or lowered in semantic/codegen passes.
+
+2. **Advanced match diagnostics**
+   - No overlap/redundancy diagnostics for case patterns.
+   - No unreachable-branch detection for wildcard-first or fully-covered prior patterns.
+
+3. **Memory/lifetime model**
+   - Current validation covers basic `del` reference checks.
+   - Ownership/borrow-style lifetime guarantees are not implemented.
+
+4. **Generic constraint internals**
+   - Inline type-set constraint resolution in `src/generics.py` is still placeholder-level (`resolve_generic_constraint`).
+
+5. **Backend semantic parity hardening**
+   - Core conformance is green, but differential/backend-equivalence checks should be expanded and kept mandatory for new language features.
 
 ---
 
-## Deferred (Still Planned)
+## Out of Scope for This Snapshot
 
-1. Labeled loops (`outer: for ...`) with syntax disambiguation.
-2. Array-programming stdlib (tensor/broadcast/linear algebra features).
-3. Alternative backends (C/native) using `src/backends/base.py`.
+- Package ecosystem, registry/distribution workflows, and broader tooling are intentionally secondary to language-core correctness.

README.md

@@ -4,7 +4,7 @@ This whole application was vibecoded using Codex and Claude Code.
 
 A Python-based compiler for A7, a statically-typed systems programming language. A7 combines the simplicity of C-style syntax with modern features like generics, type inference, and property-based pointer operations.
 
-The compiler features a complete pipeline: tokenizer, parser, 3-pass semantic analysis, AST preprocessing, and Zig code generation.
+The compiler features a complete pipeline: tokenizer, parser, 3-pass semantic analysis, AST preprocessing, and pluggable code generation backends (Zig and C).
 
 ## Inspired By
 
@@ -30,12 +30,18 @@ uv sync
 
 ## Usage
 
-Compile an A7 program to Zig:
+Compile an A7 program to Zig (default backend):
 ```bash
 uv run python main.py examples/001_hello.a7
 # Output: examples/001_hello.zig
 ```
 
+Compile an A7 program to C:
+```bash
+uv run python main.py --backend c examples/001_hello.a7
+# Output: examples/001_hello.c
+```
+
 Modes and output formats:
 ```bash
 uv run python main.py --mode tokens examples/006_if.a7                     # Tokens only
@@ -60,20 +66,21 @@ PYTHONPATH=. uv run pytest                         # All tests
 PYTHONPATH=. uv run pytest test/test_tokenizer.py  # Specific test file
 PYTHONPATH=. uv run pytest -k "generic" -v         # Targeted tests
 uv run python scripts/verify_examples_e2e.py       # Compile/build/run + output checks for all examples
+uv run python scripts/verify_examples_e2e_c.py     # Same flow via C backend + zig cc
 uv run python scripts/verify_error_stages.py       # Error-stage audit across modes and formats
 ```
 
 ## Compilation Pipeline
 
 ```
-Source (.a7) → Tokenizer → Parser → Semantic Analysis (3-pass) → AST Preprocessing → Zig Codegen → Output (.zig)
+Source (.a7) → Tokenizer → Parser → Semantic Analysis (3-pass) → AST Preprocessing → Backend Codegen (Zig/C) → Output (.zig/.c)
 ```
 
 1. **Tokenizer**. Lexes source into tokens. Handles single-token generics (`$T`), nested comments, and number formats.
 2. **Parser**. Uses recursive descent with precedence climbing. Parses all A7 constructs.
 3. **Semantic Analysis**. Runs name resolution, type checking with inference, and control flow validation.
 4. **AST Preprocessing**. Runs 9 sub-passes: sugar lowering, stdlib resolution, mutation and usage analysis, type inference, shadowing resolution, function hoisting, and constant folding.
-5. **Zig Code Generation**. Translates AST to valid Zig source code.
+5. **Backend Code Generation**. Translates AST to valid Zig or C source code.
 
 All AST traversals are iterative with no recursion. The pipeline works with Python's recursion limit set to 100.
 
@@ -86,16 +93,17 @@ All AST traversals are iterative with no recursion. The pipeline works with Pyth
 - **Memory**: Property-based pointer syntax (`.adr`, `.val`), new/delete, defer cleanup
 - **Imports**: Module system with named imports, using imports, aliased imports
 - **Generics**: Type parameters (`$T`), constraints, type sets, generic structs
-- **Code Generation**: Full A7 → Zig translation with smart var/const inference, function hoisting, shadowing prevention
+- **Code Generation**: A7 → Zig and A7 → C backends
 - **Standard Library**: Registry with io and math modules, backend-specific mappings
 - **Error Messages**: Rich formatting with source context and structured error types
 
 ## Project Status
 
-- **983 tests passing**, 9 skipped
-- **36/36 examples** pass end-to-end compile + build + run + golden-output verification
+- Test status depends on current branch state. Check with `PYTHONPATH=. uv run pytest --tb=no -q`.
+- Example end-to-end verification is available via `uv run python scripts/verify_examples_e2e.py`.
 - Parser is 100% complete for the A7 specification
 - Zig backend handles all AST node types
+- C backend targets C11 and is validated with `zig cc`
 
 ## Learn More
 

ERROR_ANALYSIS.md docs/ERROR_ANALYSIS.mdERROR_ANALYSIS.md renamed to docs/ERROR_ANALYSIS.md

@@ -1,12 +1,12 @@
 # A7 Programming Language Specification
 
-> **Implementation Status (2026-02-21)**: This specification describes the complete A7 language design. The current Python implementation (`a7-py`) provides:
+> **Implementation Status (2026-02-24)**: This specification describes the complete A7 language design. The current Python implementation (`a7-py`) provides:
 > - ✅ **Tokenizer/Lexer**: implemented
 > - ✅ **Parser**: implemented
 > - ✅ **AST generation**: implemented
-> - ✅ **Semantic pipeline**: implemented (name resolution, type checking, semantic validation), with known generic/match-expression gaps
+> - ✅ **Semantic pipeline**: implemented (name resolution, type checking, semantic validation), including match expressions, pattern type checks, and bool/enum exhaustiveness checks
 > - ✅ **Zig code generation**: implemented
-> - 📊 **Current tests**: `1039 passed, 7 failed, 0 skipped` after unskipping previously deferred semantic tests
+> - 📊 **Current tests**: `1067 passed, 0 failed, 0 skipped`
 >
 > See `MISSING_FEATURES.md` for detailed feature status and `CLAUDE.md` for development guide.
 
@@ -534,7 +534,7 @@ match color {
     }
     case Color.Green: {
         print("Green")
-        fall  // Explicit fallthrough
+        fall  // Parsed; full semantic/codegen fallthrough behavior is still being finalized
     }
     case Color.Blue: {
         print("Green or Blue")
@@ -1787,7 +1787,7 @@ match color {
     }
     case Color.Green: {
         print("Green")
-        fall  // Explicit fallthrough
+        fall  // Parsed; full semantic/codegen fallthrough behavior is still being finalized
     }
     case Color.Blue: {
         print("Green or Blue")
@@ -2831,34 +2831,28 @@ A7 supports the full ASCII character set (0-127) only. Characters outside this r
 
 ## Appendix E: Implementation Status (a7-py)
 
-Status snapshot (2026-02-21), based on running `PYTHONPATH=. uv run pytest` after unskipping deferred semantic tests:
+Status snapshot (2026-02-24), based on running `PYTHONPATH=. uv run pytest -q`:
 
 - ✅ Full compiler pipeline exists (tokenizer, parser, semantic passes, AST preprocessing, Zig backend).
 - ✅ Examples continue to pass end-to-end verification.
-- 📊 Test status: **1039 passed, 7 failed, 0 skipped**.
+- 📊 Test status: **1067 passed, 0 failed, 0 skipped**.
 
 ### E.1 Current Open Gaps
 
-1. **Match expressions in semantic type checking**
-   - `MATCH_EXPR` nodes are parsed but not yet handled by `TypeCheckingPass`.
+1. **`fall` semantic/codegen behavior**
+   - `fall` parses, but full semantic validation and backend lowering are still pending.
 
-2. **Type-set builtin in declaration expression context**
-   - `@type_set(...)` currently fails in top-level constant declarations due to expression parsing path for type arguments.
+2. **Advanced match diagnostics**
+   - Exhaustiveness for bool/enum is implemented, but overlap/redundancy diagnostics are still incomplete.
 
-3. **Constraint-aware generic arithmetic**
-   - Generic functions using arithmetic on `$T` fail without constraint propagation/type knowledge.
+3. **Memory/lifetime model depth**
+   - Basic `new`/`del` validation exists; full ownership/lifetime analysis is not complete.
 
-4. **Generic struct field substitution**
-   - Struct literal/type checks still compare against unresolved `$T/$U` fields in some paths.
+4. **Generic constraint internals**
+   - Some generic-constraint helper internals remain placeholder-level and need completion.
 
-5. **Field access on instantiated generic structs**
-   - `Box(i32)`/`Node(i32)` remain `GenericInstanceType` in field-access checks instead of being resolved to concrete struct field layouts.
-
-6. **Literal initialization for generic locals**
-   - Initializers like `total: $T = 0` need inference/coercion strategy for generic numeric contexts.
-
-7. **Recursive generic instantiation**
-   - Recursive generic structs need cycle-safe type resolution and substitution.
+5. **Backend semantic parity hardening**
+   - Differential parity checks across backends should continue expanding for new language features.
 
 ### E.2 Source Of Truth
 

docs/SPEC.md

@@ -0,0 +1,15 @@
+# Archive
+
+This folder stores old or non-essential project artifacts that were moved out of the repository root to keep the main workspace focused.
+
+Moved on 2026-02-21:
+
+- `ERROR_ANALYSIS.md` -> `docs/ERROR_ANALYSIS.md`
+- `run.sh` -> `docs/archive/tools/run.sh`
+- `fix_types.py` -> `docs/archive/tools/fix_types.py`
+- `__pycache__/main.cpython-313.pyc` -> `docs/archive/pycache/__pycache__/main.cpython-313.pyc`
+- `site/` -> `docs/archive/site/`
+
+Notes:
+
+- `docs/archive/site/node_modules` was intentionally removed because it is generated dependency output.