chore(reflaxe): guard source cross-file layout

Author: fullofcaffeine

.beads/issues.jsonl

@@ -430,6 +430,7 @@
 {"_type":"issue","id":"haxe.elixir-5tm","title":"Fix unused function warnings in TodoLive","description":"UNUSED FUNCTIONS: Three private functions in TodoLive.ex are unused: render_todo_item/2 (line 590), render_tags/1 (line 668), is_optimistically_toggled/2 (line 275). Either: (1) These are dead code - remove from Haxe source, (2) DCE should eliminate them, or (3) They should be called somewhere. Investigate in src_haxe/server/live/TodoLive.hx and fix appropriately.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-03T00:01:15Z","updated_at":"2025-12-08T17:24:29Z","closed_at":"2025-12-08T11:24:29Z","dependency_count":0,"dependent_count":1,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir-e0m","title":"Fix app-level unused variables in TodoLive","description":"APP-LEVEL WARNINGS: TodoLive.ex has many unused variables that should be fixed in the Haxe source (src_haxe/server/live/TodoLive.hx): raw_params_completed, raw_params_description, raw_params_due_date, raw_params_priority, raw_params_tags, raw_params_title, raw_params_user_id (in create_todo), broadcast_result, s_optimistic, broadcast, todo_updated, todo_updates (in toggle_todo_status), refreshed_todos, currently_selected (in handle_event). Either use these variables or remove/prefix them in Haxe source.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-03T00:01:08Z","updated_at":"2025-12-08T17:24:29Z","closed_at":"2025-12-08T11:24:29Z","dependency_count":0,"dependent_count":1,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir-upq","title":"Fix unused variable warnings - add underscore prefix in compiler","description":"COMPILER ENHANCEMENT: The compiler generates ~50+ unused variable warnings in Elixir. Variables like 'value', 'this1', 'e', 'o', 'c', 't', 'args', 'cl', 'constr', 'index' are declared but never used. Elixir convention requires prefixing unused variables with underscore (_value, _this1, etc). Fix in code generator to detect unused variables and add underscore prefix automatically. This is a systematic fix, not per-variable.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-03T00:00:59Z","updated_at":"2025-12-08T17:24:35Z","closed_at":"2025-12-08T11:24:35Z","dependency_count":0,"dependent_count":1,"comment_count":0}
+{"_type":"issue","id":"haxe.elixir.codex-0st","title":"Guard source-tree cross-file convention","description":"Extend the stdlib/source layout guard so source checkouts cannot accumulate checked-in src/**/*.cross.hx files outside the documented early haxe.Exception override. This keeps Reflaxe _std/package-flattening conventions explicit without changing compiler semantics.","acceptance_criteria":"guard:stdlib-layout fails on unexpected tracked src/**/*.cross.hx files, still allows src/haxe/Exception.cross.hx, docs/changelog mention the convention, and package/source layout validation passes.","status":"closed","priority":3,"issue_type":"task","owner":"boss@fullofcaffeine.com","created_at":"2026-07-09T15:19:27Z","created_by":"Marcelo Serpa","updated_at":"2026-07-09T15:21:36Z","started_at":"2026-07-09T15:19:40Z","closed_at":"2026-07-09T15:21:36Z","close_reason":"Extended guard:stdlib-layout to allow only src/haxe/Exception.cross.hx under tracked src/**/*.cross.hx, documented the enforcement, and verified guard:stdlib-layout, docs links, diff whitespace, path scan, and haxelib package smoke.","labels":["cleanup","packaging","reflaxe"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir.codex-et5","title":"Align extraParams null-safety macro with Reflaxe conventions","description":"Add the Reflaxe skeleton-style package-scoped nullSafety macro to Reflaxe.Elixir entrypoint HXML files. This should apply to compiler package code only, before bootstrap/init, without changing target/user semantics.","acceptance_criteria":"extraParams.hxml and repo-local haxe_libraries/reflaxe.elixir.hxml run nullSafety(\"reflaxe.elixir\") before CompilerBootstrap/CompilerInit; docs/changelog mention the convention; package smoke and representative repo-local builds pass; no user/app semantics are changed.","status":"closed","priority":3,"issue_type":"task","owner":"boss@fullofcaffeine.com","created_at":"2026-07-09T14:08:02Z","created_by":"Marcelo Serpa","updated_at":"2026-07-09T14:40:40Z","started_at":"2026-07-09T14:08:11Z","closed_at":"2026-07-09T14:40:40Z","close_reason":"Aligned entrypoint HXML with package-scoped nullSafety before bootstrap/init, documented the convention, made HaxeThrow.value nullable to satisfy the compiler-package null-safety contract, and verified package smoke, quick snapshots, examples compile/output/WAE/runtime, mix-fast, and todo-app sentinel+Playwright.","labels":["cleanup","packaging","reflaxe"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir.codex-4vd","title":"Move remaining Haxe std replacements into _std","description":"Move the remaining upstream-colliding Haxe stdlib replacement modules that still live under plain std/haxe/** into std/elixir/_std/**. Keep target-owned local additions under plain std/**. This aligns the source tree with the Reflaxe _std ownership convention without changing compiler semantics.","acceptance_criteria":"Upstream reference modules no longer live as plain std/haxe/** files unless there is a documented exception; target-owned local additions remain under std/**; guard:stdlib-layout and guard:stdlib-parity pass; affected snapshots/examples are updated only for intentional source-map/path drift; package smoke still proves Reflaxe build emits packaged .cross.hx files.","status":"closed","priority":3,"issue_type":"task","owner":"boss@fullofcaffeine.com","created_at":"2026-07-09T12:50:24Z","created_by":"Marcelo Serpa","updated_at":"2026-07-09T13:25:20Z","started_at":"2026-07-09T12:51:52Z","closed_at":"2026-07-09T13:25:20Z","close_reason":"Moved the remaining upstream-colliding plain std/haxe/** modules into std/elixir/_std/** while leaving target-owned support surfaces under std/haxe/**. Added a guard allowlist for remaining plain std/haxe/** support modules, updated docs/changelog, and refreshed generated test source maps for intentional _std path drift. Validation: npm run guard:stdlib-layout; npm run guard:stdlib-parity; npm run guard:docs-links; git diff --check; npm run test:quick; scripts/test-chunks.sh --parallel 8 --chunk-deadline 900 --timeout 120 --categories phoenix,liveview,ecto,otp,exunit,bootstrap; npm run test:haxelib-package; npm run test:examples; npm run test:examples-output; npm run test:examples-elixir; npm run test:examples-runtime; npm run test:haxe-exunit-stdlib; npm run guard:upstream-unitstd; npm run guard:hx-format; npm run test:mix-fast; todo-app async QA sentinel with Playwright e2e/smoke/*.spec.ts (5/5 passed). Path scan found only existing guard/docs examples.","labels":["cleanup","reflaxe","stdlib"],"dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"haxe.elixir.codex-oky","title":"Update stdlib parity roadmap for early source overrides","description":"After the Reflaxe _std layout cleanup, update stale stdlib parity roadmap/template references that describe early overrides as src/haxe/**/*.cross.hx. The current convention is std/elixir/_std for normal std replacements, target-owned std/** APIs, and selected src/haxe/** early overrides with only haxe.Exception using .cross.hx.","notes":"Updated stdlib parity roadmap/templates so future tasks use std/elixir/_std for normal std overrides, target-owned std/** APIs/support modules, and selected src/haxe/** early overrides. Clarified parity-report comments for plain early src/haxe/ds/*.hx modules. Validation: npm run guard:docs-links, npm run guard:stdlib-parity, npm run guard:stdlib-layout, git diff --check. Path scan reported only existing guard/docs examples.","status":"closed","priority":3,"issue_type":"task","owner":"boss@fullofcaffeine.com","created_at":"2026-07-09T11:14:55Z","created_by":"Marcelo Serpa","updated_at":"2026-07-09T11:16:34Z","started_at":"2026-07-09T11:15:08Z","closed_at":"2026-07-09T11:16:34Z","dependency_count":0,"dependent_count":0,"comment_count":0}

CHANGELOG.md

@@ -5,6 +5,7 @@
 * **reflaxe:** align stdlib override sources with the Reflaxe `_std` layout; source-tree and GitHub/Lix builds now load `std/elixir/_std` before target-owned `std` APIs so PhoenixHx/examples keep using the Elixir stdlib overrides in dev mode.
 * **reflaxe:** move remaining upstream-colliding `std/haxe/**` replacement modules into `std/elixir/_std`, leaving plain `std/haxe/**` for target-owned support surfaces.
 * **reflaxe:** align package entrypoint HXML files with Reflaxe-generated targets by applying package-scoped `nullSafety("reflaxe.elixir")` before bootstrap/init macros.
+* **reflaxe:** enforce the source-tree `.cross.hx` convention so the only checked-in `src/**/*.cross.hx` file remains the documented early `haxe.Exception` override.
 * **reflaxe:** audit vendored framework patches against upstream Reflaxe and document which local fixes remain required before they can be removed or upstreamed.
 * **reflaxe:** remove debug-only vendored framework drift while preserving required local Reflaxe patches.
 * **docs:** clarify the remaining early `src/haxe/**` overrides, including why `src/haxe/Exception.cross.hx` intentionally remains the lone source-tree `.cross.hx` file.

docs/03-compiler-development/CROSS_FILES_STAGING_MECHANISM.md

@@ -243,6 +243,9 @@ run.
 set. Upstream `haxe.Exception` is extern, so macro/eval and non-cross targets can keep resolving the
 official stdlib file. The Elixir target needs a concrete emitted base module for exception structs,
 so the early `.cross.hx` file provides that implementation only when `elixir_output` is active.
+`npm run guard:stdlib-layout` enforces that this remains the only checked-in `src/**/*.cross.hx`
+source file; ordinary target-specific std replacements should stay under `std/elixir/_std/**/*.hx`
+and be materialized as packaged `.cross.hx` files by Reflaxe build.
 
 Because `src/` is visible in more situations (tools, JS/genes builds, etc.), those early overrides often use:
 

docs/04-api-reference/STANDARD_LIBRARY_HANDLING.md

@@ -133,7 +133,8 @@ There are three current shapes:
 - `src/haxe/Exception.cross.hx` is intentionally still target-suffixed. Upstream `haxe.Exception`
   is extern, so macro/eval and non-cross targets can keep resolving upstream. Elixir output needs a
   concrete base module for exception structs, so the `.cross.hx` file provides `Reflaxe.Exception`
-  behind `#if elixir_output ... #else extern ... #end`.
+  behind `#if elixir_output ... #else extern ... #end`. The source layout guard enforces that this
+  is the only checked-in `src/**/*.cross.hx` file.
 - `src/haxe/ds/{ArraySort,BalancedTree,EnumValueMap,ListSort}.hx` are dual-mode plain `.hx` modules:
   `#if macro` gives eval a small implementation, while `#else` exposes an extern surface or target
   diagnostic surface so generated Elixir does not emit the canonical mutable stdlib implementation.

docs/05-architecture/CROSS_OVERRIDES_AND_MULTI_TARGET_HARDENING.md

@@ -104,7 +104,8 @@ Recommended next steps:
 1. Narrow Haxe 4 bootstrap activation so raw `Cross` is not treated as sufficient target identity.
 2. Add explicit mixed-target detection/fail-fast behavior when sibling target libraries are active together.
 3. Keep `src/haxe/Exception.cross.hx` documented as the intentional lone source-tree `.cross.hx`
-   early override, not just another stdlib file.
+   early override, not just another stdlib file. `npm run guard:stdlib-layout` enforces that no
+   additional checked-in `src/**/*.cross.hx` files are added.
 4. Add a focused coexistence smoke or regression test if a deterministic test shape can be designed.
 
 ## Local sibling references

scripts/ci/check-stdlib-source-layout.sh

@@ -21,6 +21,25 @@ if [[ -n "$tracked_std_cross" ]]; then
   exit 1
 fi
 
+tracked_src_cross="$(
+  git -C "$ROOT_DIR" ls-files 'src/**/*.cross.hx' 'src/*.cross.hx' 2>/dev/null || true
+)"
+if [[ -n "$tracked_src_cross" ]]; then
+  unexpected_src_cross="$(
+    printf '%s\n' "$tracked_src_cross" | grep -Fxv 'src/haxe/Exception.cross.hx' || true
+  )"
+  if [[ -n "$unexpected_src_cross" ]]; then
+    {
+      echo "checked-in src/**/*.cross.hx files must not grow beyond the documented"
+      echo "early haxe.Exception override. Put ordinary std replacements under"
+      echo "std/elixir/_std/**/*.hx and let Reflaxe build generate packaged"
+      echo ".cross.hx files. Found unexpected source-tree cross files:"
+      printf '%s\n' "$unexpected_src_cross" | sed -n '1,80p'
+    } >&2
+    exit 1
+  fi
+fi
+
 if [[ ! -d "$ROOT_DIR/std/elixir/_std" ]]; then
   fail "missing std/elixir/_std source override root"
 fi
@@ -112,4 +131,4 @@ then
   fail "haxelib.json reflaxe.stdPaths does not match the source-layout convention"
 fi
 
-echo "[guard:stdlib-layout] OK: std overrides use std/elixir/_std source layout"
+echo "[guard:stdlib-layout] OK: std overrides use std/elixir/_std source layout and source cross-file convention"