AILang/docs/journals/2026-05-12-iter-ext-cli.1.md

iter ext-cli.1 — CLI accepts .ail (Form A) source files alongside .ail.json

Date: 2026-05-12 Started from: efecbaa Status: DONE Tasks completed: 4 of 4

Summary

Closes the loop opened by this morning's .ailx → .ail rename. Every path-taking ail subcommand (check, build, run, manifest, render, prose, merge-prose, describe, emit-ir, diff, workspace, deps) now accepts a .ail (Form A) input as well as .ail.json (Form B). For .ail paths the subcommand parses through ailang_surface::parse in-line and proceeds with the same loaded Module value .ail.json would have produced; the binary semantics are extension-agnostic.

Architecture: a new ailang_surface::{load_module, load_workspace} pair dispatches on file extension. A new injection point in ailang_core::workspace::load_workspace_with<F> lets the surface crate plug in an extension-aware loader without ailang-core having to import ailang-surface (which would close a crate cycle). Import resolution in workspace::visit now prefers a .ail sibling over a .ail.json sibling of the same module name. The CLI binary's 18 ailang_core::load_* callsites all switched to the new ailang_surface::load_*. Surface parse failures route through the existing workspace_error_to_diagnostic channel as a new SurfaceParse variant of WorkspaceLoadError, so ail check --json foo.ail on a malformed .ail returns a parseable JSON diagnostic with code surface_parse_error instead of the pre-iter misleading json: expected value at line 1 column 1 fall-through.

Per-task notes

• iter ext-cli.1.1: WorkspaceLoadError::SurfaceParse { path, message } variant added to ailang_core::workspace; load_workspace refactored into a thin wrapper around a new pub fn load_workspace_with<F>(entry, loader: F) with F: Fn(&Path) -> Result<Module, WorkspaceLoadError> + Copy; visit's signature gained the loader parameter and its import-path construction now does .ail-first / .ail.json-fallback; new test load_workspace_with_custom_loader_is_called pins the injection. tempfile added as ailang-core dev-dependency.
• iter ext-cli.1.2: new crates/ailang-surface/src/loader.rs with pub fn load_module (extension-dispatching: .ail → parse, else delegate to ailang_core::load_module) and pub fn load_workspace (calls load_workspace_with(entry, load_module)); lib.rs re-exports both. Three integration tests in crates/ailang-surface/tests/loader.rs pin the dispatch on each form individually + the mixed-extension workspace case. tempfile added as ailang-surface dev-dependency.
• iter ext-cli.1.3: every ailang_core::load_module / ailang_core::load_workspace callsite in crates/ail/src/main.rs (18 sites total) replaced with ailang_surface::load_module / ailang_surface::load_workspace. Workspace-build placeholder W::SurfaceParse { .. } => None arm added to workspace_error_to_diagnostic (replaced in Task 4) so the exhaustive match compiles. Two new E2E tests in crates/ail/tests/e2e.rs: ail_check_accepts_ail_source and ail_run_accepts_ail_source_with_same_stdout_as_ail_json.
• iter ext-cli.1.4: placeholder arm replaced with proper W::SurfaceParse { path, message } => Some(Diagnostic::error( "surface_parse_error", message).with_ctx({"path": ...})) — mirroring the SchemaMismatch arm's builder pattern. DESIGN.md §Decision 6 / "CLI" bullet gained the one-paragraph addendum (verbatim from the plan, dated). New ct1 test ail_check_json_on_ail_with_syntax_error_returns_structured_diagnostic pins the JSON-diagnostic shape.

Plus one E2E coverage test added during Phase 3: load_workspace_prefers_ail_when_both_extensions_exist — protects the .ail-first precedence when both extensions are present for the same module (the existing 1.2 test only exercised the fallback half).

Concerns

• Diagnostic code convention drift (Boss-corrected pre-commit). The plan-specified code surface_parse_error used snake_case; every other diagnostic code in the codebase is kebab-case (type-mismatch, unbound-var, over-strict-mode, reuse-as-shape-mismatch, ...). Boss verified the convention via git grep over crates/ailang-check/src and crates/ail/src before commit and aligned the literal to surface-parse-error at three sites: the SurfaceParse arm in workspace_error_to_diagnostic (crates/ail/src/main.rs) and the two matching strings in crates/ail/tests/ct1_check_cli.rs (the rustdoc on the test + the assert_eq! against first["code"]). The plan file is left at the snake_case form as historical record; the source of truth is now the corrected code.
• bench/check.py first run noisy. First execution showed 4 regressions on latency.{explicit,implicit}_at_rc.{p99_9,max}_us (tail-latency tier). Re-runs (×2) returned 0 regressed (one even showed 4 improvements beyond tolerance). This is the same latency.explicit_at_rc.* cluster audit-cma and audit-ms already documented as nondeterministic; the iter's actual code change introduces ONE extra surface_path.is_file() syscall per import-resolution step plus a single-byte extension check per load, neither of which can move us-scale tail latencies. Net: baseline left pristine, consistent with the last two audits.

Known debt

• The ail parse subcommand is still the only way to materialise a stable .ail.json snapshot from a .ail source. Now that every subcommand silently dispatches .ail through the parser, one might argue for a "did you mean ail parse?" hint on paths with non-.ail/non-.ail.json extensions. The roadmap note for ext-cli.1 mentions this as a possible same-iter or follow-up scope; nothing surfaced as load-bearing during impl, deferring.

Files touched

Code:

• crates/ailang-core/Cargo.toml (+ tempfile dev-dep)
• crates/ailang-core/src/workspace.rs (SurfaceParse variant, load_workspace_with, visit threading, .ail-first precedence, new unit test)
• crates/ailang-surface/Cargo.toml (+ tempfile dev-dep)
• crates/ailang-surface/src/lib.rs (mod loader + re-exports)
• crates/ailang-surface/src/loader.rs (NEW)
• crates/ailang-surface/tests/loader.rs (NEW; 4 tests)
• crates/ail/src/main.rs (18 callsite rewires + SurfaceParse diagnostic arm)
• crates/ail/tests/e2e.rs (2 new E2E tests)
• crates/ail/tests/ct1_check_cli.rs (1 new diagnostic-shape test)

Spec / metadata:

• docs/DESIGN.md (§Decision 6 / CLI bullet addendum)
• Cargo.lock (tempfile dev-dep transitive)

Stats

bench/orchestrator-stats/2026-05-12-iter-ext-cli.1.json