coverage-gap stage 2: utils/preflight — run CI's gates locally

COVERAGE_GAP.md

@@ -79,3 +79,43 @@ Process: per-stage plan → implement → review, same as FIXED_ARRAY_REWORK.md.
 - Nightly cron on daspkg-index building every index package against daslang
   master — external ABI breakage surfaces as a nightly signal instead of
   inside an unrelated PR's extended_checks.
+
+## Stage 2 follow-ups (found while building utils/preflight, 2026-06-11)
+
+- **`.das_package` examples need a CLEAN daspkg install to be testable.**
+  `examples/games/sequence` resolves requires against a gitignored local
+  install (`modules/das-cards`) that only the smoke script refreshes — a
+  stale copy produced phantom compile errors (missing `card_mesh_ttf_path`)
+  against a green master. Options, discussable: (a) preflight scans for
+  `.das_package`, daspkg-installs fresh, then compile-checks — makes a
+  verify tool mutate + hit the network; (b) keep install-then-test inside
+  each example's smoke script (status quo, sequence only); (c) a separate
+  CI job that fresh-installs and tests every `.das_package`-bearing example
+  — pairs naturally with the Stage 4 nightly index cron. Leaning (c) with
+  preflight staying read-only.
+- **JIT-to-exe BUNDLE exes fail to load locally while master CI is green.**
+  Two data points, same family: `exe_paths_module_resolve` ctest
+  (`uses_sqlite.exe`, 0xC0000135 DLL-not-found, bundle layout) and the
+  sequence smoke's bundled `sequence.exe --smoke` (0xC0000139
+  entrypoint-not-found, fresh daspkg install + release, all artifacts
+  shipped). Triage so far: a trivial `daslang -exe` probe links AND runs
+  clean with the Dyn DLLs colocated; clearing `.jitted_scripts` changes
+  nothing; and a fully fresh one-shot rebuild (runtime DLLs + all shipped
+  modules + exe relinked together) still loads 0xC0000139 — so it is NOT
+  artifact staleness. Remaining suspect: the DLL-flavor daslang config
+  (local `.vscode` build) vs CI's static daslang, in the bundle exe's
+  load-time import chain. Chase both together.
+- **Binary-staleness warning.** A `bin/.../daslang` older than the tree
+  produces convincing-but-wrong gate output (a stale binary's das2rst
+  regenerated handmade stubs under pre-rename `rtti` names). preflight
+  could compare the binary mtime against the newest `src/` commit and
+  WARN before running binary-derived gates.
+- **Gate-duration baseline + regression warning.** Persist per-gate wall
+  times locally (gitignored) after each run; on the next run compare
+  against the recorded baseline and WARN when a gate is far off — ~10%
+  drift is noise, ~2x is indicative of a regression (compiler slowdown,
+  a lint rule gone pathological, doc-build growth). Care: per-changed-
+  file gates (lint, cpp-syntax) scale with the diff size, so normalize
+  per file or baseline only the fixed-cost gates (format sweep, dasgen,
+  docs, test suites). Pairs with the binary-staleness warning — both
+  are "preflight sanity-checks its own run" features.

skills/filesystem.md

@@ -169,12 +169,13 @@ if (r is error) {
 ## Temp files & dirs
 
 ```das
-let dir = create_temp_directory("build_") ?? ""    // null/empty on failure
-let f   = create_temp_file("dump_", ".log") ?? ""
-let td  = temp_directory() ?? ""
+var err : string
+let dir = create_temp_directory("build_", err)     // "" + err set on failure
+let f   = create_temp_file("dump_", ".log", err)
+let td  = temp_directory(err)
 ```
 
-All three return absolute paths; the `_result` variants surface a real error string if creation failed (disk full, permission denied, etc.).
+All three return absolute paths (empty string on failure, with the `error` out-param set). There are NO zero/short-arg optional-returning forms — `temp_directory()` is a compile error. The `_result` variants (`temp_directory_result()`, `create_temp_file_result(prefix, ext)`, `create_temp_directory_result(prefix)`) wrap the same calls into `fs_result_string` for exhaustive matching.
 
 ## Disk space
 

skills/make_pr.md

@@ -2,6 +2,8 @@
 
 Before creating a pull request, complete ALL of the following steps in order. Do not skip steps. If any step fails, fix the issue before proceeding.
 
+**Shortcut:** `daslang utils/preflight/main.das -- --full` runs most of the mechanical gates below in one command (`skills/preflight.md` maps each gate to its CI lane). The steps here remain the authority on fix policy and on the judgment steps (dupe triage, workaround audit, doc stubs) the tool can't do.
+
 ## 0. Sync with origin/master and rebase the branch
 
 **Always do this first.** If you skip it, a stale local `master` will cause your squashed commit to absorb other already-merged PRs as if they were branch-original work — the PR ends up touching files it has no business touching.

skills/preflight.md

@@ -6,8 +6,14 @@ was an **oracle mismatch** — a gate CI enforces that no local step mirrored 
 not a wrong change. This file maps every PR-triggered lane to its exact local
 mirror, or says honestly that there isn't one.
 
-A `utils/preflight` tool automating the common tiers is planned
-(`COVERAGE_GAP.md` Stage 2); until it lands, these are the manual commands.
+**`utils/preflight` automates these gates.** `daslang utils/preflight/main.das`
+runs the fast tier (format + lint + clang syntax pass on changed C++, seconds);
+`-- --full` adds dasgen freshness, the CI-only-das compile sweep, the six doc
+gates, ctest, the interp/JIT/AOT suites, and the sequence smoke. `--list-gates`
+shows the menu; `--only <names>` / `--skip <names>` select subsets. Gates whose
+host tool or module is missing report `SKIP` with an install/rebuild hint. The
+tables below remain the reference for what each gate mirrors and for running
+any step by hand.
 
 **Conventions.** `<daslang>` = your compiler binary: `bin/Release/daslang.exe`
 (Windows MSVC multi-config), `bin/daslang` (Ninja single-config — what CI's

utils/preflight/README.md

@@ -0,0 +1,32 @@
+# preflight
+
+Run CI's gates locally before pushing. The CI-lane ↔ gate mapping and the
+manual commands this tool automates live in
+[skills/preflight.md](https://github.com/GaijinEntertainment/daScript/blob/master/skills/preflight.md).
+
+```bash
+# fast tier (seconds): format --verify, lint changed .das, clang syntax pass on changed C++
+daslang utils/preflight/main.das
+
+# full tier: adds dasgen freshness, CI-only-das compile sweep, the six doc
+# gates, ctest -L small, interpreter/JIT/AOT suites, sequence smoke
+daslang utils/preflight/main.das -- --full
+
+# subset / introspection
+daslang utils/preflight/main.das -- --list-gates
+daslang utils/preflight/main.das -- --only docs,ci-das
+daslang utils/preflight/main.das -- --skip tests-aot --full
+```
+
+Cross-platform (Windows / macOS / Linux+WSL): subprocesses go through
+`popen_argv` (no shell) — except the sequence gate, which by design runs CI's
+own smoke scripts under pwsh/bash. The C++ syntax pass uses `clang-cl /Zs` on
+Windows (preferring the VS-bundled clang — the same binary CI's ClangCL
+toolset uses) and `clang -fsyntax-only` elsewhere, and a gate whose host tool
+or module is missing reports `SKIP` with an install/rebuild hint instead of
+passing silently. Exit code is non-zero when any gate fails.
+
+`ci_only_das.txt` lists the in-repo das surface that no default local build
+compiles (dasOpenGL today); see the header comment there before adding
+entries — surfaces that pull external daspkg packages belong to the
+`sequence` gate, not the compile sweep.

utils/preflight/ci_only_das.txt

@@ -0,0 +1,12 @@
+# CI-only das surface: in-repo files no default local build compiles, swept by
+# the preflight `ci-das` gate with `daslang -compile-only`.
+# Format: <glob> | <native modules whose absence means SKIP, comma-separated> | <rebuild hint>
+# A compile failure whose missing prerequisite is NOT in the allow-skip list is a FAIL.
+#
+# Only list files whose requires resolve entirely in-repo. Surfaces that pull
+# external daspkg packages (examples/games/sequence -> das-cards) belong to the
+# `sequence` gate instead — its ci_smoke_test script installs the deps fresh,
+# while a bare -compile-only would read whatever stale gitignored install is
+# lying around and report phantom errors.
+modules/dasOpenGL/opengl/*.das | glfw, opengl | rebuild with -DDAS_GLFW_DISABLED=OFF
+modules/dasOpenGL/glsl/*.das | glfw, opengl | rebuild with -DDAS_GLFW_DISABLED=OFF