feat(build): improve explain safety and graph fallback

Author: GaspardKirira

include/vix/cli/cache/ArtifactCache.hpp

@@ -281,6 +281,10 @@ namespace vix::cli::cache
         const std::string &signature,
         const std::string &projectFingerprint,
         const std::string &buildTarget,
+        const std::string &preset,
+        const std::string &buildType,
+        const std::string &target,
+        const std::string &compiler,
         const std::vector<ProjectInput> &currentInputs);
 
     /**

include/vix/cli/process/Process.hpp

@@ -102,6 +102,11 @@ namespace vix::cli::process
      */
     bool verbose = false;
 
+    /**
+     * @brief Explains why Vix rebuilds files or targets.
+     */
+    bool explain = false;
+
     /**
      * @brief Optional project directory passed with `--dir`.
      */

src/ErrorHandler.cpp

@@ -30,6 +30,8 @@
 #include <unordered_set>
 #include <vector>
 #include <fstream>
+#include <cstdlib>
+#include <cctype>
 
 #include <vix/cli/Style.hpp>
 #include <vix/cli/build/BuildStyle.hpp>
@@ -102,11 +104,47 @@ namespace
   {
     const std::string &message = err.message;
 
+    if (message.find("No such file or directory") != std::string::npos ||
+        message.find("file not found") != std::string::npos)
+    {
+      return "Check that the header exists and that its directory is listed in include_dirs, target_include_directories, or your compiler include paths.";
+    }
+
+    if (message.find("fatal error:") != std::string::npos &&
+        message.find("#include") != std::string::npos)
+    {
+      return "A header could not be found. Check the include path or the header name.";
+    }
+
     if (message.find("use of undeclared identifier 'std'") != std::string::npos)
+    {
       return "Include the required standard header before using std names.";
+    }
+
+    if (message.find("use of undeclared identifier") != std::string::npos)
+    {
+      return "Declare the symbol before use, include the right header, or check the namespace.";
+    }
+
+    if (message.find("was not declared in this scope") != std::string::npos)
+    {
+      return "Declare the symbol before use, include the right header, or move the function definition above the call.";
+    }
+
+    if (message.find("does not name a type") != std::string::npos)
+    {
+      return "Check that the type is declared before use and that the correct header is included.";
+    }
 
     if (message.find("expected ';'") != std::string::npos)
+    {
       return "Add the missing semicolon, often on the previous line.";
+    }
+
+    if (message.find("expected primary-expression") != std::string::npos)
+    {
+      return "Check the expression syntax near this location, especially missing operators, parentheses, or variables.";
+    }
 
     if (message.find("no matching function for call to") != std::string::npos)
     {
@@ -120,11 +158,15 @@ namespace
       return "Check argument types, overloads, const qualifiers, and references.";
     }
 
-    if (message.find("was not declared in this scope") != std::string::npos)
-      return "Declare the symbol before use, include the right header, or move the function definition above the call.";
+    if (message.find("undefined reference to") != std::string::npos)
+    {
+      return "A symbol is declared but not linked. Check missing .cpp files, libraries, or target_link_libraries.";
+    }
 
     if (message.find("defined but not used") != std::string::npos)
+    {
       return "Remove the unused function or mark it intentionally unused.";
+    }
 
     return {};
   }
@@ -302,7 +344,22 @@ namespace vix::cli
 
       print_hint("run with --verbose to inspect the full build output");
 
-      if (!cleanedLog.empty())
+      const bool debugOutput = []()
+      {
+        const char *level = std::getenv("VIX_LOG_LEVEL");
+
+        if (!level || !*level)
+          return false;
+
+        std::string value(level);
+
+        for (char &c : value)
+          c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+
+        return value == "debug" || value == "trace";
+      }();
+
+      if (debugOutput && !cleanedLog.empty())
       {
         std::cerr << "\n"
                   << GRAY
@@ -315,6 +372,10 @@ namespace vix::cli
         if (cleanedLog.back() != '\n')
           std::cerr << "\n";
       }
+      else
+      {
+        print_hint("run with VIX_LOG_LEVEL=debug to inspect the full compiler output");
+      }
 
       return false;
     }

src/build/BuildGraph.cpp

@@ -507,6 +507,16 @@ namespace vix::cli::build
         return BuildNodeKind::Config;
       }
 
+      /*
+       * Utility/phony/generated outputs are intentionally imported as Config.
+       *
+       * They are useful as graph dependencies, but they are not safe direct
+       * Graph Executor targets yet. BuildGraphExecutor will reject them and
+       * fallback to CMake/Ninja.
+       */
+      if (edge.kind == NinjaEdgeKind::Utility)
+        return BuildNodeKind::Config;
+
       return BuildNodeKind::Unknown;
     }
 
@@ -592,12 +602,23 @@ namespace vix::cli::build
       if (!edge.valid())
         return false;
 
+      /*
+       * Compile commands are imported from compile_commands.json because that
+       * gives Vix the exact compiler argv, working directory and object output.
+       */
       if (edge.kind == NinjaEdgeKind::Compile)
         return false;
 
       if (edge.kind == NinjaEdgeKind::Unknown)
         return false;
 
+      /*
+       * Import Link/Archive/Copy/Install/Utility edges.
+       *
+       * The executor will decide later if a target is safe to execute through
+       * Graph Executor. Importing the DAG is useful even when execution falls
+       * back to CMake/Ninja.
+       */
       return true;
     }
   } // namespace
@@ -863,6 +884,16 @@ namespace vix::cli::build
 
     std::size_t imported = 0;
 
+    std::unordered_map<std::string, std::string> outputToTask;
+
+    for (const auto &kv : tasks_)
+    {
+      const BuildTask &task = kv.second;
+
+      for (const std::string &outputId : task.outputs)
+        outputToTask[outputId] = task.id;
+    }
+
     for (const NinjaEdge &edge : ninjaBuild->edges)
     {
       if (!should_import_ninja_edge(edge))
@@ -881,11 +912,10 @@ namespace vix::cli::build
       task.workingDirectory = ninjaBuild->directory;
 
       /*
-       * Do not expand Ninja rule commands here.
+       * We intentionally delegate non-compile Ninja edges back to Ninja.
        *
-       * build.ninja is already a complete execution graph. For now we import
-       * the DAG structure only. Execution remains delegated to Ninja/CMake until
-       * Vix has a full Ninja variable expander and target-aware executor.
+       * Vix imports the DAG and target metadata here, but does not yet expand
+       * Ninja variables or reimplement every CMake-generated build rule.
        */
       task.command = {
           "ninja",
@@ -895,44 +925,39 @@ namespace vix::cli::build
 
       task.commandHash = command_hash_for_argv(task.command);
 
-      for (const fs::path &input : edge.explicitInputs)
+      std::vector<std::string> inputNodeIds;
+
+      auto import_input = [&](const fs::path &input)
       {
         const BuildNodeKind inputKind = node_kind_from_ninja_input(input);
 
         BuildNode inputNode = make_file_build_node(inputKind, input);
 
         /*
          * Keep Ninja import cheap.
-         * scan_project() and load_dependency_files() already hash real project
-         * inputs where needed. Ninja edges may reference many generated files.
+         * Real source/header hashes are provided by scan_project() and .d files.
+         * Ninja can reference many generated/internal files.
          */
         inputNode.hash.clear();
 
         add_node(inputNode);
+
         task.add_input(inputNode.id);
-      }
+        inputNodeIds.push_back(inputNode.id);
 
-      for (const fs::path &input : edge.implicitInputs)
-      {
-        const BuildNodeKind inputKind = node_kind_from_ninja_input(input);
+        const auto producerIt = outputToTask.find(inputNode.id);
+        if (producerIt != outputToTask.end())
+          task.add_dependency(producerIt->second);
+      };
 
-        BuildNode inputNode = make_file_build_node(inputKind, input);
-        inputNode.hash.clear();
+      for (const fs::path &input : edge.explicitInputs)
+        import_input(input);
 
-        add_node(inputNode);
-        task.add_input(inputNode.id);
-      }
+      for (const fs::path &input : edge.implicitInputs)
+        import_input(input);
 
       for (const fs::path &input : edge.orderOnlyInputs)
-      {
-        const BuildNodeKind inputKind = node_kind_from_ninja_input(input);
-
-        BuildNode inputNode = make_file_build_node(inputKind, input);
-        inputNode.hash.clear();
-
-        add_node(inputNode);
-        task.add_input(inputNode.id);
-      }
+        import_input(input);
 
       for (const fs::path &output : edge.outputs)
       {
@@ -945,7 +970,7 @@ namespace vix::cli::build
         BuildNode outputNode = make_file_build_node(outputKind, output);
         outputNode.hash.clear();
 
-        for (const auto &inputId : task.inputs)
+        for (const auto &inputId : inputNodeIds)
           outputNode.add_dependency(inputId);
 
         add_node(outputNode);
@@ -956,6 +981,10 @@ namespace vix::cli::build
         continue;
 
       add_task(task);
+
+      for (const std::string &outputId : task.outputs)
+        outputToTask[outputId] = task.id;
+
       ++imported;
     }