Improve build tooling and code quality

Add clang-format/clang-tidy targets (optional, found via Homebrew
LLVM hints). Fix macOS SDK path for Homebrew clang-tidy. Switch
FetchContent to tarballs, set CMP0135 policy. Add helpful first-run
error with setup instructions when config is missing. Apply
clang-format, fix clang-tidy warnings (const-correctness, nodiscard,
designated initializers, explicit nullptr checks).

Author: matlimatli

.clang-format

@@ -0,0 +1,11 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+ColumnLimit: 100
+PointerAlignment: Left
+ReferenceAlignment: Left
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+BreakBeforeBraces: Attach
+SortIncludes: CaseSensitive
+IncludeBlocks: Preserve

.clang-tidy

@@ -12,7 +12,16 @@ Checks: >
   -cppcoreguidelines-avoid-magic-numbers,
   -readability-magic-numbers,
   -cppcoreguidelines-pro-bounds-pointer-arithmetic,
-  -misc-include-cleaner
+  -misc-include-cleaner,
+  -bugprone-easily-swappable-parameters,
+  -cppcoreguidelines-avoid-const-or-ref-data-members,
+  -cppcoreguidelines-pro-type-member-init,
+  -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access,
+  -modernize-return-braced-init-list,
+  -bugprone-exception-escape,
+  -performance-enum-size,
+  -readability-convert-member-functions-to-static,
+  -cppcoreguidelines-pro-bounds-array-to-pointer-decay
 WarningsAsErrors: ''
 HeaderFilterRegex: 'include/.*\.h$'
 FormatStyle: file

CMakeLists.txt

@@ -1,4 +1,5 @@
 cmake_minimum_required(VERSION 3.20)
+cmake_policy(SET CMP0135 NEW)
 project(HowUtility VERSION 1.0 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
@@ -30,8 +31,6 @@ endif()
 
 # Fetch dependencies (downloads may take a moment on first configure)
 include(FetchContent)
-set(FETCHCONTENT_QUIET OFF)
-
 message(STATUS "Fetching nlohmann/json 3.12.0...")
 set(JSON_Install OFF CACHE BOOL "" FORCE)
 FetchContent_Declare(json
@@ -74,6 +73,46 @@ if(BUILD_TESTS)
 
     include(GoogleTest)
     gtest_discover_tests(how_tests)
+
+    # 'make test' rebuilds before running tests
+    add_custom_target(check
+        COMMAND ${CMAKE_CTEST_COMMAND} --output-on-failure
+        DEPENDS how_tests
+    )
+endif()
+
+# Optional clang-tidy target
+file(GLOB_RECURSE ALL_SOURCES src/*.cpp include/*.h)
+find_program(CLANG_TIDY clang-tidy
+    HINTS /opt/homebrew/opt/llvm/bin /usr/local/opt/llvm/bin)
+if(CLANG_TIDY)
+    # When using Homebrew clang-tidy with Apple Clang, pass the SDK path
+    set(CLANG_TIDY_EXTRA_ARGS "")
+    if(APPLE)
+        execute_process(COMMAND xcrun --show-sdk-path OUTPUT_VARIABLE SDKROOT OUTPUT_STRIP_TRAILING_WHITESPACE)
+        set(CLANG_TIDY_EXTRA_ARGS "--extra-arg=-isysroot${SDKROOT}")
+    endif()
+    add_custom_target(tidy
+        COMMAND ${CLANG_TIDY} -p ${CMAKE_BINARY_DIR} ${CLANG_TIDY_EXTRA_ARGS} ${ALL_SOURCES}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        COMMENT "Running clang-tidy..."
+    )
+endif()
+
+# Optional clang-format target
+find_program(CLANG_FORMAT clang-format
+    HINTS /opt/homebrew/opt/llvm/bin /usr/local/opt/llvm/bin)
+if(CLANG_FORMAT)
+    add_custom_target(format
+        COMMAND ${CLANG_FORMAT} -i ${ALL_SOURCES}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        COMMENT "Running clang-format..."
+    )
+    add_custom_target(format-check
+        COMMAND ${CLANG_FORMAT} --dry-run --Werror ${ALL_SOURCES}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        COMMENT "Checking clang-format..."
+    )
 endif()
 
 # Install

include/ConfigManager.h

@@ -4,7 +4,7 @@
 #include <unordered_map>
 
 class ConfigManager {
-public:
+  public:
     explicit ConfigManager(std::string path = "~/.config/how/config");
 
     void load();
@@ -17,8 +17,8 @@ class ConfigManager {
     [[nodiscard]] bool allowInsecureSsl() const;
     [[nodiscard]] bool isLoaded() const;
 
-private:
-    std::string resolvePath(const std::string& path) const;
+  private:
+    [[nodiscard]] std::string resolvePath(const std::string& path) const;
     void checkPermissions(const std::string& resolved) const;
     void parseFile(const std::string& resolved);
     [[nodiscard]] std::string get(const std::string& key, const std::string& fallback = "") const;

include/ContextGatherer.h

@@ -3,14 +3,14 @@
 #include <string>
 
 class ContextGatherer {
-public:
+  public:
     void gather();
 
     [[nodiscard]] std::string os() const;
     [[nodiscard]] std::string shell() const;
     [[nodiscard]] std::string workingDirectory() const;
 
-private:
+  private:
     std::string os_ = "unknown";
     std::string shell_ = "unknown";
     std::string workingDirectory_ = "unknown";

include/HistoryManager.h

@@ -1,7 +1,7 @@
 #pragma once
 
-#include <string>
 #include <optional>
+#include <string>
 #include <utility>
 
 struct Exchange {
@@ -10,7 +10,7 @@ struct Exchange {
 };
 
 class HistoryManager {
-public:
+  public:
     explicit HistoryManager(std::string path = "~/.cache/how/history");
 
     /// Load the previous exchange, if any.
@@ -19,8 +19,8 @@ class HistoryManager {
     /// Save the current exchange, creating the directory and enforcing 0600.
     void save(const std::string& userQuery, const std::string& assistantReply) const;
 
-private:
-    std::string resolvePath() const;
+  private:
+    [[nodiscard]] std::string resolvePath() const;
 
     std::string path_;
 };

include/LLMClient.h

@@ -11,15 +11,14 @@ struct Message {
 };
 
 class LLMClient {
-public:
+  public:
     explicit LLMClient(const Provider& provider, bool allowInsecureSsl = false);
 
     /// Send a chat completion request and return the assistant's reply.
-    [[nodiscard]] std::string complete(
-        const std::string& systemPrompt,
-        const std::vector<Message>& messages) const;
+    [[nodiscard]] std::string complete(const std::string& systemPrompt,
+                                       const std::vector<Message>& messages) const;
 
-private:
+  private:
     static size_t writeCallback(char* data, size_t size, size_t nmemb, std::string* out);
 
     const Provider& provider_;

include/PromptBuilder.h

@@ -3,7 +3,7 @@
 #include <string>
 
 class PromptBuilder {
-public:
+  public:
     void setQuery(const std::string& query);
     void setOS(const std::string& os);
     void setShell(const std::string& shell);
@@ -12,7 +12,7 @@ class PromptBuilder {
     [[nodiscard]] std::string buildSystemPrompt() const;
     [[nodiscard]] std::string buildUserMessage() const;
 
-private:
+  private:
     std::string query_;
     std::string os_;
     std::string shell_;

include/Provider.h

@@ -1,34 +1,31 @@
 #pragma once
 
+#include <nlohmann/json.hpp>
 #include <string>
 #include <vector>
-#include <nlohmann/json.hpp>
 
 struct Message;
 
 class Provider {
-public:
+  public:
     Provider() = default;
 
     /// Create a provider by name. Throws if name is unknown.
-    static Provider create(const std::string& name,
-                           const std::string& apiKey,
-                           const std::string& model,
-                           const std::string& customEndpoint = "");
+    static Provider create(const std::string& name, const std::string& apiKey,
+                           const std::string& model, const std::string& customEndpoint = "");
 
     [[nodiscard]] std::string endpoint() const;
     [[nodiscard]] std::vector<std::string> headers() const;
-    [[nodiscard]] nlohmann::json formatRequest(
-        const std::string& systemPrompt,
-        const std::vector<Message>& messages) const;
+    [[nodiscard]] nlohmann::json formatRequest(const std::string& systemPrompt,
+                                               const std::vector<Message>& messages) const;
     [[nodiscard]] std::string parseResponse(const nlohmann::json& json) const;
     [[nodiscard]] const std::string& name() const;
 
-private:
+  private:
     enum class Format { OpenAI, Anthropic, Google };
 
-    Provider(std::string name, std::string endpoint, std::string apiKey,
-             std::string model, Format format);
+    Provider(std::string name, std::string endpoint, std::string apiKey, std::string model,
+             Format format);
 
     std::string name_;
     std::string endpoint_;

src/ConfigManager.cpp

@@ -6,13 +6,12 @@
 #include <stdexcept>
 #include <sys/stat.h>
 
-ConfigManager::ConfigManager(std::string path)
-    : path_(std::move(path)) {}
+ConfigManager::ConfigManager(std::string path) : path_(std::move(path)) {}
 
 std::string ConfigManager::resolvePath(const std::string& path) const {
     if (path.starts_with("~/")) {
         const char* home = std::getenv("HOME");
-        if (!home) {
+        if (home == nullptr) {
             throw std::runtime_error("HOME environment variable is not set");
         }
         return std::string(home) + path.substr(1);
@@ -23,14 +22,23 @@ std::string ConfigManager::resolvePath(const std::string& path) const {
 void ConfigManager::checkPermissions(const std::string& resolved) const {
     struct stat st{};
     if (stat(resolved.c_str(), &st) != 0) {
-        throw std::runtime_error("Cannot stat config file: " + resolved);
+        throw std::runtime_error("Config file not found: " + resolved +
+                                 "\n"
+                                 "Create it with:\n\n"
+                                 "  mkdir -p ~/.config/how\n"
+                                 "  cat > ~/.config/how/config << 'EOF'\n"
+                                 "  default_provider = mistral\n"
+                                 "  mistral_api_key = YOUR_API_KEY\n"
+                                 "  EOF\n"
+                                 "  chmod 600 ~/.config/how/config\n\n"
+                                 "Replace YOUR_API_KEY with a key from your provider.\n"
+                                 "See the README for other providers and options.");
     }
 
-    mode_t perms = st.st_mode & 0777;
-    if (perms & ~static_cast<mode_t>(0600)) {
+    const mode_t perms = st.st_mode & 0777;
+    if ((perms & ~static_cast<mode_t>(0600)) != 0) {
         std::ostringstream msg;
-        msg << "Config file permissions are too open (0"
-            << std::oct << perms << "). "
+        msg << "Config file permissions are too open (0" << std::oct << perms << "). "
             << "Run: chmod 600 " << resolved;
         throw std::runtime_error(msg.str());
     }
@@ -103,7 +111,7 @@ std::string ConfigManager::customEndpoint() const {
 }
 
 bool ConfigManager::allowInsecureSsl() const {
-    auto val = get("allow_insecure_ssl", "false");
+    const auto val = get("allow_insecure_ssl", "false");
     return val == "true" || val == "1" || val == "yes";
 }