v0.4.0: Type Safety Modes — Two Axes of Type Control (DD-009)

[larimonious]

v0.4.0: Type Safety Modes — Two Axes of Type Control (DD-009)

Design doc: plans/009-ntnt-type-safety-modes.md
10 commits | 43 files changed | +2,558 / -959 lines | 960 tests passing

---

What this PR does

Introduces two independent axes of type control, world-class error messages, generics in the type checker, accurate line numbers on all runtime errors, and unified execution contexts for lib/route/middleware modules.

Lint axis (NTNT_LINT_MODE / --warn-untyped / --strict) — controls how thoroughly code is statically analyzed before it runs.

Runtime axis (NTNT_TYPE_MODE) — controls what happens when types mismatch at runtime:

• strict → crash (fail-closed, for auth/payments/safety-critical apps)
• warn → log [WARN] + continue (default)
• forgiving → silent degradation (pre-v0.4 behavior)

---

Commits

Commit	What
dd4122c	Core: TypeMode/LintMode enums, config.rs, 7 TypeMode-aware resilience points, version → 0.4.0
0ab1460	Copilot R1: --warn-untyped/--strict flags, field access TypeMode, test fixes
24a1c18	Copilot R2: NTNT_LINT_MODE precedence bug, RuntimeError constructor consistency
0f1d861	Phase 6: handle_template_error() DRY, warning dedup, error categorization, NTNT_STRICT deprecation, docs
22eb976	Copilot R3: DiagnosticKind enum, clear_type_warnings() at boundaries, --strict/--warn-untyped conflict
4e7a092	Phase 7: TypeContext error messages, T? + type aliases, deeper inference, real generics
cc175ae	Copilot R4: generic conflict detection (multi-arg T consistency), 4 new generic tests
e5fe366	Line numbers: Located wrapping for all declarations, line field on 5 error types, source snippets
3d32eac	Lib context: define_stdlib() in all 3 module loading paths — fixes findings #69, #73
7cbab97	Self-review: unwrap_located() in 3 lint paths, remove unnecessary #[allow(dead_code)]

---

Feature breakdown

Two Axes of Type Control (Phases 1–3)

• TypeMode enum: Strict / Warn / Forgiving — 7+ TypeMode-aware resilience points:
  • Index ([]) type mismatch
  • for..in on non-collection values
  • Template expression/filter/raw/for-loop errors (consolidated into handle_template_error())
  • Field access on non-struct/map values
• LintMode enum: Default / Warn / Strict
• NTNT_TYPE_MODE, NTNT_LINT_MODE env vars — OnceLock caching in prod, re-read in tests
• CLI: --warn-untyped (warnings, non-fatal) and --strict (errors, fatal), mutually exclusive
• NTNT_STRICT deprecated with [DEPRECATED] message → NTNT_LINT_MODE=strict
• Warning dedup via thread-local HashSet — same location warns once per request, not 50×
• DiagnosticKind enum replaces brittle substring matching for lint promotion

World-Class Error Messages (Phase 7.1)

• TypeContext struct: expected / got / hint fields
• Terminal rendering with │ expected: / └─ hint: formatting and color
• Binary op errors show operator symbol + conversion hints
• All stdlib modules migrated from TypeError(String) → type_error(msg) constructors

T? Shorthand + Type Aliases (Phase 7.2)

• T? shorthand for Optional<T> in annotations
• Array type literal syntax: [Int], [String]
• Function type annotations: (T1, T2) -> ReturnType
• type Handler = (Request) -> Response — function type aliases

Deeper Type Inference (Phase 7.3)

• Return type inference from function body
• Collection and map literal element type inference
• Lambda parameter type inference from call context

Real Generics in Type Checker (Phase 7.4)

• FunctionSig.type_params stores generic parameter names
• unify_type_params() + unify_one() + substitute_type_params() — structural unification
• identity<T>(42) infers return type Int (not Any)
• Multi-arg consistency: fn f<T>(a: T, b: T) called with (Int, String) correctly errors
• Type params preserved via Type::Named instead of collapsing to Any

Accurate Line Numbers on All Errors (Phase 8.1)

Root cause found: declaration() in parser called let_declaration(), function_declaration(), etc. directly — none were wrapped in Located. Only statement() (if/while/for/return) was wrapped. Every runtime error from a let/fn/struct/import had zero line info.

• declaration() now captures line/col before parsing and wraps all results in Located
• TypeError, RuntimeError, UndefinedVariable, UndefinedFunction, ArityMismatch all carry a line field
• at_line() builder method — Located handler annotates errors as they propagate
• Parser EOF errors now show last token position instead of line 0
• format_error() shows file:line header + source snippet with context for all error types

# Before: no location info
error[E003]
  --> Type error: Cannot apply '-' to String and Int

# After: file + line + source context
error[E003]
  --> /path/to/file.tnt:3
  = Type error: Cannot apply '-' to String and Int
   |
   2 | let y = 42
   3 | let result = x - y
   4 | print(result)
   |
  expected: String
     found: Int

Unified Execution Contexts (Phase 8.2)

Root cause: load_module_exports(), process_route_file(), load_middleware_file() all created a fresh Environment and called define_builtins() — but not define_stdlib(). The stdlib module registry was empty, so import { concat } from "std/string" couldn't resolve in lib files.

• Added define_stdlib() to all three module loading paths
• Fixes findings #69 (concat() unavailable in lib) and #73 (multiple stdlib builtins missing in lib)
• lib, route, and middleware modules now have identical execution environments

Self-Review Catch (Phase 8.3)

Bug found during review: check_stmt_for_issues(), the import collision checker, and collect_used_names() in main.rs all pattern-matched directly on Statement::Let, Statement::Function, etc. Since declaration() now wraps these in Located, they silently fell through to _ => {} — all declaration-level lint checks were being skipped.

• Added unwrap_located() calls in the three affected lint paths

---

Testing

960 tests (up from 919 at branch start, +41 new):

• 15 type safety mode tests (TypeMode behavior, LintMode, warning dedup)
• 5 language feature tests (T?, type aliases, array type literals)
• 7 generic type checker tests (identity, conflict detection, array unification)
• 7 parser server block tests updated for Located wrapping
• All 919 existing tests pass unchanged

Staging validated on v0.4.0 binary:

• Intent check: 6/6 features, 10/10 scenarios, 12/12 assertions ✅
• All admin pages 200 ✅
• API endpoints (GET/POST/list) ✅
• Hot-reload ✅
• ntnt lint --warn-untyped: 230 annotation warnings across 47 files ✅
• ntnt lint --strict: annotations promoted to errors ✅
• Zero panics, zero type warnings in logs ✅

---

Breaking changes

None. All new behavior is opt-in.

• Default NTNT_TYPE_MODE=warn — logs warnings but does not crash (same behavior as DD-008 forgiving + visibility)
• Default NTNT_LINT_MODE=default — only checks annotated code (same as before)
• NTNT_STRICT still works but prints a deprecation notice

---

What's not in this PR (future work)

• Phase 4: Coercion controls in strict mode (Int→Float promotion, "str" + 42, truthy/falsy in if) — language design decisions needing separate discussion
• Phase 5: Interfaces/traits, literal types, recursive types, intersection types, const/readonly, tuples
• Phase 7.5: LSP server
• Bounded generics (fn sum<T: Numeric>), generic structs

[Copilot]

Pull request overview

This PR introduces DD-009’s “two-axis” type control by adding runtime TypeMode and lint-time LintMode configuration, then wiring TypeMode into previously “resilient” runtime behaviors (indexing, for..in, and template error boundaries). It also updates intent-check server readiness probing and bumps the crate version to v0.4.0.

Changes:

• Add src/config.rs with TypeMode/LintMode enums and env-driven getters (cached outside tests).
• Update interpreter resilience points to follow NTNT_TYPE_MODE semantics (strict/warn/forgiving), plus add tests covering the new modes.
• Change intent-check readiness from HTTP polling to TCP connect probing; bump version to 0.4.0.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/main.rs	Switch intent-check server readiness probe to TCP connect + early-exit detection.
src/lib.rs	Export new config module from the crate.
src/interpreter.rs	Apply TypeMode to for..in, indexing mismatches, and template error boundaries; add TypeMode-related tests.
src/config.rs	New env-based configuration module for runtime/lint type modes with test-aware caching behavior.
Cargo.toml	Bump package version to 0.4.0.
Cargo.lock	Update locked package version to 0.4.0.

[larimonious]

Copilot Review Responses

TCP readiness probe (src/main.rs): Valid point about false positives. For intent checks this is acceptable — port is randomly assigned via pick_available_port(), collisions are unlikely, and this is dev/CI tooling where false positives surface quickly. The previous HTTP polling had a real pipe buffer deadlock on verbose apps (DD-008 finding). Could add PID verification later if needed.

config.rs doc wording: ✅ Fixed in 0ab1460 — changed to "non-test builds" to match #[cfg(not(test))].

Template error HTML comments leaking (both instances): ✅ Fixed in 0ab1460 — added template_warn_comment() helper. Returns generic <!-- template error --> in production, detailed error only in dev mode (!is_production_mode()). All 6 template error boundaries updated.

---

Additional changes in this push:

• --warn-untyped CLI flag + NTNT_LINT_MODE env var (Phase 2 lint integration)
• Strict lint now promotes missing-annotation warnings to errors
• Lambda parameter annotation warnings
• Field access on non-struct/map is now TypeMode-aware (Phase 3)
• macOS CI fix (recursion test stack overflow)
• Regenerated docs

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 5 comments.

[larimonious]

Second Review Round — All 5 Comments Addressed (24a1c18)

1. NTNT_LINT_MODE precedence (src/main.rs:1783): Fixed. Now checks if NTNT_LINT_MODE env var is explicitly set before falling back to legacy NTNT_STRICT/project config. NTNT_LINT_MODE=default properly overrides NTNT_STRICT=1.

2. Field access error type consistency (src/interpreter.rs:4320): Changed from TypeError to RuntimeError with "Type mismatch:" prefix, matching the index mismatch pattern.

3. test_for_in_warn_skips assertion (src/interpreter.rs:11464): Now asserts Value::Int(0) to verify the loop body was actually skipped, not just that it returned Ok.

4. Strict lint exit code assertion (tests/type_checker_tests.rs:443): Added assert!(code != 0) — strict mode with annotation errors must exit non-zero.

5. Missing return type exit code (tests/type_checker_tests.rs:493): Same fix — asserts non-zero exit code.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 10 comments.

[larimonious]

Addressed all 10 new Copilot comments in 22eb976:

Structural improvements:

• DiagnosticKind enum replaces substring matching for annotation promotion — future wording changes won't silently break strict mode
• clear_type_warnings() wired up at eval() + call_function_by_name() — dedup set resets per request, no unbounded growth
• strict_check_with_file() now respects NTNT_LINT_MODE=strict so the deprecation warning is honest

CLI/docs:

• --strict and --warn-untyped are now mutually exclusive (conflicts_with)
• --warn-untyped description updated to cover all strict-mode warnings (not just annotations)

Code quality:

• Variable shadowing (code → source/exit_code) fixed in 3 tests
• handle_template_error doc comment corrected

947 tests passing.

[larimonious]

Phase 7.1–7.4 pushed in 4e7a092:

7.1 Error messages (Elm/Rust-tier):

error[E003]
  --> Cannot apply '-' to String and Int
  │ expected: compatible types for '-'
  │     found: String - Int
  └─ hint: Convert to string first: string(value) + "..."

• TypeContext struct with expected/got/hint — 747 call sites migrated to typed constructors
• format_error() now renders the │/└─ structure in terminal output

7.2 Type syntax:

• Function type aliases: type Handler = (String) -> String
• Array type literal: fn sum(nums: [Int]) -> Int
• Both verified working in 5 new tests

7.3 Inference: Already deeper than I thought — return type inference, collection inference, lambda context inference all verified working.

7.4 Real generics:

• fn identity<T>(x: T) -> T — T preserved as Type::Named, not collapsed to Any
• Structural unification: identity(42) → T = Int → return Int
• let result: String = identity(42) now correctly errors
• Works for nested types: Array<T>, T?, (T) -> T

956 tests passing.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated 3 comments.

[larimonious]

Round 4 addressed in cc175ae, all 22 threads now resolved.

1. Generic conflict detection — unify_one() now tracks conflicts instead of silently keeping the first binding. fn f<T>(a: T, b: T) with (Int, String) produces: "Type parameter 'T' in 'f': conflicting types Int and String"

2. let mut in test — fixed to match ntnt mutability semantics

3. 4 generic unification tests — covers correct usage, wrong assignment, conflicting params, and array element unification

960 tests, all passing.

[larimonious]

Round 5 — Line Number Accuracy Fix

Problems found

1. Runtime errors had zero line tracking — TypeError, UndefinedVariable, ArityMismatch, etc. carried no line info at all. Only parser/lexer errors did.
2. Parser EOF errors reported line 0 — when the parser hit unexpected EOF, current_line() returned 0 instead of the last token's position.
3. Declarations not wrapped in Located — let, fn, struct, enum, import, etc. bypassed the Located wrapper. Only bare statements (if/while/for/return) were wrapped.

Fixes

• parser.rs: current_line()/current_column() fall back to previous() when at EOF
• parser.rs: consume() uses current_line() (with EOF fallback)
• parser.rs: all paths through declaration() now emit a Located wrapper
• error.rs: added line: usize field to TypeError, RuntimeError, UndefinedVariable, UndefinedFunction, ArityMismatch
• error.rs: at_line() builder method for annotating errors
• interpreter.rs: Statement::Located handler wraps errors with at_line
• main.rs: format_error shows file:line + source snippet for all runtime errors

Before vs after

# Before
error[E003]
  --> Type error: Cannot apply '-' to String and Int

# After
error[E003]
  --> /path/to/file.tnt:3
  = Type error: Cannot apply '-' to String and Int
   |
   2 | let y = 42
   3 | let result = x - y
   4 | print(result)
   |

960 tests passing.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 43 changed files in this pull request and generated 1 comment.

[Copilot]

Generic argument type-checking currently only skips parameters whose type is exactly a type param (e.g., T). For parameters like [T], Option<T>, Map<String, T>, the pre-unification compatibility check will still fail against concrete typed arguments (e.g., [Int]), because Type::Named("T") is not compatible with Int. Consider unifying first and substituting type params into parameter types before checking, or extending the skip logic to recursively detect type params inside compound types so generic functions can be called with typed collections.