perf(cli): cache single-file Vix builds

Author: GaspardKirira

include/vix/cli/commands/run/RunDetail.hpp

@@ -296,6 +296,7 @@ namespace vix::commands::RunCommand::detail
     fs::path stderrLogPath;
 
     std::string cacheKey;
+    std::string rebuildReason;
     bool cacheHit = false;
     bool needsRebuild = true;
   };
@@ -713,6 +714,11 @@ namespace vix::commands::RunCommand::detail
    */
   DirectScriptCacheState load_direct_script_cache_state(const DirectScriptPlan &plan);
 
+  /**
+   * @brief Persist positive direct script cache metadata after a successful compile.
+   */
+  bool persist_direct_script_cache_metadata(const DirectScriptPlan &plan);
+
   // ===========================================================================
   // Script mode execution
   // ===========================================================================

include/vix/cli/commands/run/detail/DirectScriptRunner.hpp

@@ -41,6 +41,11 @@ namespace vix::commands::RunCommand::detail
    */
   DirectScriptCacheState load_direct_script_cache_state(const DirectScriptPlan &plan);
 
+  /**
+   * @brief Persist positive direct script cache metadata after a successful compile.
+   */
+  bool persist_direct_script_cache_metadata(const DirectScriptPlan &plan);
+
   /**
    * @brief Build a direct compile plan for a probed script.
    */

src/commands/run/RunScript.cpp

@@ -1441,6 +1441,54 @@ namespace vix::commands::RunCommand::detail
       return ensure_script_executable_exists(state);
     }
 
+    const char *script_fallback_reason_name(ScriptFallbackReason reason) noexcept
+    {
+      switch (reason)
+      {
+      case ScriptFallbackReason::None:
+        return "none";
+      case ScriptFallbackReason::UsesCompiledDeps:
+        return "uses compiled dependencies";
+      case ScriptFallbackReason::UsesVixRuntime:
+        return "uses Vix runtime without direct installation";
+      case ScriptFallbackReason::UsesOrm:
+        return "uses ORM";
+      case ScriptFallbackReason::UsesDatabase:
+        return "uses database";
+      case ScriptFallbackReason::UsesMySql:
+        return "uses MySQL";
+      case ScriptFallbackReason::RequiresCMakeTargets:
+        return "requires CMake targets";
+      case ScriptFallbackReason::UnsupportedFlags:
+        return "unsupported compiler flags";
+      case ScriptFallbackReason::UnsupportedLayout:
+        return "unsupported layout";
+      case ScriptFallbackReason::Unknown:
+        return "unknown";
+      }
+
+      return "unknown";
+    }
+
+    bool trace_script_strategy_enabled(const Options &opt)
+    {
+      if (opt.verbose)
+        return true;
+
+      const char *env = vix::utils::vix_getenv("VIX_RUN_TRACE_CACHE");
+      return env && *env && std::string(env) != "0";
+    }
+
+    void print_cmake_fallback_trace(const Options &opt, const ScriptProbeResult &probe)
+    {
+      if (!trace_script_strategy_enabled(opt))
+        return;
+
+      std::cerr << "script strategy: cmake fallback\n";
+      std::cerr << "fallback reason: "
+                << script_fallback_reason_name(probe.fallbackReason) << "\n";
+    }
+
     int build_script_executable_internal(const Options &opt, fs::path &exePath)
     {
       Options o = opt;
@@ -1472,7 +1520,7 @@ namespace vix::commands::RunCommand::detail
 
         const DirectScriptCacheState cache = load_direct_script_cache_state(directPlan);
 
-        if (directPlan.shouldCompile)
+        if (cache.needsRebuild)
         {
           const LiveRunResult build = run_cmd_live_filtered_capture(
               directPlan.compileCmd,
@@ -1501,14 +1549,15 @@ namespace vix::commands::RunCommand::detail
             return build.exitCode != 0 ? build.exitCode : 1;
           }
 
-          // Do not rewrite legacy cache metadata here.
-          // The direct runner owns the cache metadata format.
+          if (!persist_direct_script_cache_metadata(directPlan))
+            std::cerr << "warning: unable to persist direct script cache metadata\n";
         }
 
         exePath = directPlan.binaryPath;
         return 0;
       }
 
+      print_cmake_fallback_trace(o, probe);
       const CMakeScriptPlan cmakePlan = make_cmake_script_plan(o, probe);
       ScriptProjectState state = make_state_from_cmake_plan(cmakePlan);
 
@@ -1647,6 +1696,7 @@ namespace vix::commands::RunCommand::detail
       return run_single_cpp_direct(o, directPlan);
     }
 
+    print_cmake_fallback_trace(o, probe);
     const CMakeScriptPlan cmakePlan = make_cmake_script_plan(o, probe);
     return run_single_cpp_cmake(o, cmakePlan);
   }

src/commands/run/RunScriptHelpers.cpp

@@ -299,13 +299,29 @@ namespace vix::commands::RunCommand::detail
 
   std::optional<fs::path> find_vix_lib()
   {
+    std::vector<fs::path> prefixes;
+
+    const char *home = vix::utils::vix_getenv(
+#ifdef _WIN32
+        "USERPROFILE"
+#else
+        "HOME"
+#endif
+    );
+
+    if (home && *home)
+      prefixes.push_back(fs::path(home) / ".vix" / "lib");
+
+    prefixes.emplace_back("/usr/local/lib");
+    prefixes.emplace_back("/usr/lib");
+
     std::error_code ec;
 
-    for (const char *prefix : {"/usr/local/lib", "/usr/lib"})
+    for (const auto &prefix : prefixes)
     {
       for (const char *name : {"libvix.a", "libvix.so", "libvix.dylib"})
       {
-        const fs::path p = fs::path(prefix) / name;
+        const fs::path p = prefix / name;
         ec.clear();
         if (fs::exists(p, ec) && !ec)
           return p;
@@ -318,8 +334,23 @@ namespace vix::commands::RunCommand::detail
   std::vector<fs::path> find_vix_all_module_libs()
   {
     std::vector<fs::path> result;
+    std::vector<fs::path> prefixes;
     std::error_code ec;
 
+    const char *home = vix::utils::vix_getenv(
+#ifdef _WIN32
+        "USERPROFILE"
+#else
+        "HOME"
+#endif
+    );
+
+    if (home && *home)
+      prefixes.push_back(fs::path(home) / ".vix" / "lib");
+
+    prefixes.emplace_back("/usr/local/lib");
+    prefixes.emplace_back("/usr/lib");
+
     static const char *modules[] = {
         "libvix_core.a",
         "libvix_net.a",
@@ -344,14 +375,14 @@ namespace vix::commands::RunCommand::detail
         "libvix_error.a",
         nullptr};
 
-    for (const char *prefix : {"/usr/local/lib", "/usr/lib"})
+    for (const auto &prefix : prefixes)
     {
       bool found = false;
       std::vector<fs::path> batch;
 
       for (int i = 0; modules[i] != nullptr; ++i)
       {
-        const fs::path p = fs::path(prefix) / modules[i];
+        const fs::path p = prefix / modules[i];
         ec.clear();
         if (fs::exists(p, ec) && !ec)
         {