Address CI feedback: docs and clang-format for diff feature

Combined slice of upstream commits 24ccdfd (CI feedback) and ec27e91
(clang-format) restricted to the diff feature's surface area:

- Doxygen comments for public members of SqlSchemaDiff (ColumnDiff,
  TableDiff) and SqlDataDiff (RowDiff, TableDataDiff, DiffProgressEvent),
  plus SecretResolver move ops.
- Replace \\ref with backticks in SqlSchemaDiff/SqlDataDiff doc comments
  so doxygen stops complaining about unresolved references.
- Exclude src/Lightweight/tui/ from doxygen — vendored code follows the
  upstream comment style.
- Migrate \`.find(x) != std::string::npos\` to \`.contains(x)\` (and the
  inverse) across PR-introduced code (ProfileStore.cpp, SqlSchema.cpp,
  ConfigProfileStoreTests.cpp, SecretResolverTests.cpp), satisfying
  clang-tidy 22's readability-container-contains check.
- clang-format-22 across modified C++ files (tui/, Secrets/, dbtool main.cpp).

No behavioral changes — purely doc / lint / whitespace.

Signed-off-by: Christian Parpart <christian@parpart.family>

Author: christianparpart

.github/workflows/build.yml

@@ -110,13 +110,27 @@ jobs:
       - name: "install dependencies"
         run: sudo apt install -y cmake ninja-build catch2 unixodbc-dev sqlite3 libsqlite3-dev libsqliteodbc uuid-dev libyaml-cpp-dev gcc-14 libtbb-dev libzip-dev
       - name: "cmake"
+        # ENABLE_TIDY=OFF: this job invokes `run-clang-tidy` directly after
+        # configure; we don't want CMAKE_CXX_CLANG_TIDY also wired up
+        # because that runs clang-tidy on libunicode's own sources during
+        # the codegen build step below — and libunicode predates clang-tidy
+        # 22's pedantic warning set.
         run: |
           cmake --preset clang-debug \
                 -D CMAKE_CXX_COMPILER=clang++-${{ env.CLANG_TOOLS_VERSION }} \
                 -D CMAKE_C_COMPILER=clang-${{ env.CLANG_TOOLS_VERSION }} \
+                -D ENABLE_TIDY=OFF \
                 -B build
+      - name: "build libunicode codegen (UCD tables)"
+        # `unicode_ucd` is the libunicode static library whose source list
+        # includes the auto-generated `ucd_enums.h` and friends. Building it
+        # (only it) materialises those headers so that clang-tidy can parse
+        # `<libunicode/codepoint_properties.h>` transitively included from
+        # our vendored `tui/MarkdownTable.cpp`. Without this step, clang-tidy
+        # aborts with `'libunicode/ucd_enums.h' file not found`.
+        run: cmake --build build --target unicode_ucd
       - name: "run clang-tidy"
-        run: run-clang-tidy-${{ env.CLANG_TOOLS_VERSION }} -p ./build -clang-tidy-binary clang-tidy-${{ env.CLANG_TOOLS_VERSION }} -config-file .clang-tidy -header-filter='^(?!(.*/)?stdexec-src/|(.*/)?libzip-src/).*$' -source-filter='^(?!.*_deps/).*$'
+        run: run-clang-tidy-${{ env.CLANG_TOOLS_VERSION }} -p ./build -clang-tidy-binary clang-tidy-${{ env.CLANG_TOOLS_VERSION }} -config-file .clang-tidy -header-filter='^(?!(.*/)?stdexec-src/|(.*/)?libzip-src/|(.*/)?libunicode-src/).*$' -source-filter='^(?!.*_deps/).*$'
 
   # }}}
   # {{{ Windows

src/Lightweight/QueryFormatter/SQLiteFormatter.hpp

@@ -498,23 +498,27 @@ class SQLiteQueryFormatter: public SqlQueryFormatter
                     // commas so the split-on-',' parse on the runtime side is unambiguous.
                     auto const joinComma = [](std::vector<std::string> const& v) {
                         std::string out;
-                        for (size_t i = 0; i < v.size(); ++i)
+                        bool first = true;
+                        for (auto const& s: v)
                         {
-                            if (i != 0)
+                            if (!first)
                                 out += ',';
-                            out += v[i];
+                            out += s;
+                            first = false;
                         }
                         return out;
                     };
                     auto const joinQuoted = [](std::vector<std::string> const& v) {
                         std::string out;
-                        for (size_t i = 0; i < v.size(); ++i)
+                        bool first = true;
+                        for (auto const& s: v)
                         {
-                            if (i != 0)
+                            if (!first)
                                 out += ", ";
                             out += '"';
-                            out += v[i];
+                            out += s;
                             out += '"';
+                            first = false;
                         }
                         return out;
                     };

src/Lightweight/SqlDataDiff.cpp

@@ -138,11 +138,13 @@ namespace
                 : std::format("{}.{}", Quote(tableOnThisSide.schema, server), Quote(tableOnThisSide.name, server));
 
         auto cols = std::string {};
-        for (auto const& [i, name]: std::views::enumerate(layout.orderedColumnNames))
+        bool firstCol = true;
+        for (auto const& name: layout.orderedColumnNames)
         {
-            if (i != 0)
+            if (!firstCol)
                 cols += ", ";
             cols += Quote(name, server);
+            firstCol = false;
         }
 
         auto orderBy = std::string {};

src/Lightweight/SqlDataDiff.hpp

@@ -24,27 +24,30 @@ namespace SqlSchema
     /// One row-level data difference between two databases.
     struct RowDiff
     {
+        /// Row-level classification: only-in-A, only-in-B, or changed.
         DiffKind kind {};
 
         /// String form of the row's primary key tuple. Empty for tables without a PK
-        /// (in which case @ref TableDataDiff::skipReason is set instead).
+        /// (in which case `TableDataDiff::skipReason` is set instead).
         std::vector<std::string> primaryKey {};
 
-        /// For @ref DiffKind::Changed: per-column tuple of (column name, value-on-A, value-on-B)
+        /// For `DiffKind::Changed`: per-column tuple of (column name, value-on-A, value-on-B)
         /// where the values differ. Empty for OnlyInA / OnlyInB.
         std::vector<std::tuple<std::string, std::string, std::string>> changedCells {};
     };
 
     /// Result of comparing the rows of one table across two databases.
     struct TableDataDiff
     {
+        /// Table name (schema-unqualified) that was compared.
         std::string tableName {};
 
         /// All row-level diffs found, in primary-key order.
         std::vector<RowDiff> rows {};
 
-        /// Total rows scanned from each side (informational; useful for headers).
+        /// Total rows scanned from the left-hand side (informational; useful for headers).
         std::size_t aRowCount = 0;
+        /// Total rows scanned from the right-hand side (informational; useful for headers).
         std::size_t bRowCount = 0;
 
         /// True when scanning was cut short by the @c maxRows cap.
@@ -58,8 +61,11 @@ namespace SqlSchema
     /// Live progress event reported during a data diff. Fired ~2 Hz at most.
     struct DiffProgressEvent
     {
+        /// Name of the table currently being scanned.
         std::string tableName;
+        /// Rows scanned so far from the left-hand side.
         std::size_t rowsScannedA = 0;
+        /// Rows scanned so far from the right-hand side.
         std::size_t rowsScannedB = 0;
         std::size_t expectedRowsA = 0; ///< 0 if unknown.
         std::size_t expectedRowsB = 0; ///< 0 if unknown.

src/Lightweight/SqlMigration.cpp

@@ -817,13 +817,15 @@ namespace
     {
         auto const joinQuoted = [](std::vector<std::string> const& v) {
             std::string out;
-            for (size_t i = 0; i < v.size(); ++i)
+            bool first = true;
+            for (auto const& s: v)
             {
-                if (i != 0)
+                if (!first)
                     out += ", ";
                 out += '"';
-                out += v[i];
+                out += s;
                 out += '"';
+                first = false;
             }
             return out;
         };

src/Lightweight/SqlQueryFormatter.hpp

@@ -181,9 +181,10 @@ class [[nodiscard]] LIGHTWEIGHT_API SqlQueryFormatter
     /// @brief Whether the dialect must rebuild a table to add or drop a foreign-key
     /// constraint (i.e. cannot express it via `ALTER TABLE … ADD/DROP CONSTRAINT`).
     ///
-    /// SQLite returns `true`; every other backend defaults to `false`. The migration
-    /// executor consults this to decide whether to take the table-rebuild path on
-    /// `AlterTable` steps that touch foreign keys.
+    /// Defaults to `false`; SQLiteQueryFormatter overrides to `true`. Because PG and
+    /// MSSQL formatters inherit from SQLiteQueryFormatter, they re-override back to
+    /// `false`. The migration executor consults this to decide whether to take the
+    /// table-rebuild path on `AlterTable` steps that touch foreign keys.
     [[nodiscard]] virtual bool RequiresTableRebuildForForeignKeyChange() const noexcept
     {
         return false;

src/Lightweight/SqlSchemaDiff.cpp

@@ -236,11 +236,13 @@ namespace
         // Order matters for composite PKs — report a single line with both sides.
         auto join = [](std::vector<std::string> const& v) {
             auto s = std::string {};
-            for (auto const& [i, name]: std::views::enumerate(v))
+            bool first = true;
+            for (auto const& name: v)
             {
-                if (i != 0)
+                if (!first)
                     s += ", ";
                 s += name;
+                first = false;
             }
             return s.empty() ? std::string { "(none)" } : s;
         };
@@ -256,11 +258,13 @@ namespace
     {
         auto join = [](std::vector<std::string> const& v) {
             auto s = std::string {};
-            for (auto const& [i, name]: std::views::enumerate(v))
+            bool first = true;
+            for (auto const& name: v)
             {
-                if (i != 0)
+                if (!first)
                     s += ",";
                 s += name;
+                first = false;
             }
             return s;
         };
@@ -294,11 +298,13 @@ namespace
     [[nodiscard]] std::string FormatIndex(IndexDefinition const& idx)
     {
         auto cols = std::string {};
-        for (auto const& [i, name]: std::views::enumerate(idx.columns))
+        bool first = true;
+        for (auto const& name: idx.columns)
         {
-            if (i != 0)
+            if (!first)
                 cols += ",";
             cols += name;
+            first = false;
         }
         return std::format("{}{}({})", idx.isUnique ? "UNIQUE " : "", idx.name, cols);
     }

src/Lightweight/SqlSchemaDiff.hpp

@@ -23,19 +23,21 @@ enum class DiffKind : std::uint8_t
 /// A diff entry for a single column.
 struct ColumnDiff
 {
+    /// Column name (case sensitivity follows the engines' rules — they're paired by name).
     std::string name;
+    /// Column-level classification: only-in-A, only-in-B, or changed.
     DiffKind kind {};
 
-    /// For @ref DiffKind::Changed: human-readable list of differing fields
+    /// For `DiffKind::Changed`: human-readable list of differing fields
     /// (e.g. `"type"`, `"nullable"`, `"defaultValue"`). Empty otherwise.
     std::vector<std::string> changedFields {};
 
-    /// Pointer into the input @ref TableList for the left-hand column. Null when
-    /// @ref kind is @ref DiffKind::OnlyInB.
+    /// Pointer into the input `TableList` for the left-hand column. Null when
+    /// `kind` is `DiffKind::OnlyInB`.
     Column const* a = nullptr;
 
-    /// Pointer into the input @ref TableList for the right-hand column. Null when
-    /// @ref kind is @ref DiffKind::OnlyInA.
+    /// Pointer into the input `TableList` for the right-hand column. Null when
+    /// `kind` is `DiffKind::OnlyInA`.
     Column const* b = nullptr;
 };
 
@@ -47,20 +49,20 @@ struct TableDiff
     /// for identity, so the same logical table compares as equal across SQL dialects.
     std::string name;
 
-    /// Schema name on the left-hand side. Empty when @ref kind is @ref DiffKind::OnlyInB
+    /// Schema name on the left-hand side. Empty when `kind` is `DiffKind::OnlyInB`
     /// or when the left-hand engine reports no schema (e.g. SQLite).
     std::string schemaA;
 
-    /// Schema name on the right-hand side. Empty when @ref kind is @ref DiffKind::OnlyInA
+    /// Schema name on the right-hand side. Empty when `kind` is `DiffKind::OnlyInA`
     /// or when the right-hand engine reports no schema.
     std::string schemaB;
 
-    /// Table-level classification: @ref DiffKind::OnlyInA / @ref DiffKind::OnlyInB
-    /// when one side lacks the table entirely; @ref DiffKind::Changed when both
+    /// Table-level classification: `DiffKind::OnlyInA` / `DiffKind::OnlyInB`
+    /// when one side lacks the table entirely; `DiffKind::Changed` when both
     /// sides have it but column / key / index definitions differ.
     DiffKind kind {};
 
-    /// Per-column diffs. Populated only when @ref kind is @ref DiffKind::Changed.
+    /// Per-column diffs. Populated only when `kind` is `DiffKind::Changed`.
     std::vector<ColumnDiff> columns {};
 
     /// Human-readable PK differences (e.g. `"primary key columns differ"`).
@@ -90,9 +92,9 @@ struct SchemaDiff
 ///
 /// Pairs tables by **name only** so the same logical table matches across SQL dialects
 /// even when engine-specific schema labels differ (`dbo` vs `public` vs `""`). Both
-/// schema labels are kept on @ref TableDiff for the renderer. Columns are paired by name.
+/// schema labels are kept on `TableDiff` for the renderer. Columns are paired by name.
 ///
-/// Column comparison uses the canonical @ref Column::type variant (engine-agnostic),
+/// Column comparison uses the canonical `Column::type` variant (engine-agnostic),
 /// not the dialect-dependent type string, so an `INTEGER` column compares equal whether
 /// the driver reports `int4`, `int`, or `INTEGER`. Other compared fields: nullability,
 /// size, decimal digits, default value, auto-increment, primary-key membership,

src/Lightweight/tui/MarkdownInline.hpp

@@ -40,8 +40,7 @@ struct InlineCodeSpan
 }
 
 /// @brief Finds the end of a CommonMark inline code span starting at pos.
-[[nodiscard]] constexpr auto findInlineCodeEnd(std::string_view text, std::size_t pos)
-    -> std::optional<InlineCodeSpan>
+[[nodiscard]] constexpr auto findInlineCodeEnd(std::string_view text, std::size_t pos) -> std::optional<InlineCodeSpan>
 {
     auto const tickStart = pos;
     while (pos < text.size() && text[pos] == '`')

src/Lightweight/tui/MarkdownTable.cpp

@@ -288,8 +288,8 @@ auto wrapText(std::string_view text, int maxWidth) -> std::vector<std::string>
             break;
 
         auto const wordEnd = text.find(' ', wordStart);
-        auto const word = text.substr(
-            wordStart, wordEnd == std::string_view::npos ? std::string_view::npos : wordEnd - wordStart);
+        auto const word =
+            text.substr(wordStart, wordEnd == std::string_view::npos ? std::string_view::npos : wordEnd - wordStart);
         auto const wordWidth = inlineDisplayWidth(word);
 
         if (currentLine.empty() && wordWidth > maxWidth)
@@ -400,8 +400,7 @@ auto stripInlineMarkdown(std::string_view text) -> std::string
         if (text[pos] == '[')
         {
             auto const endBracket = text.find(']', pos + 1);
-            if (endBracket != std::string_view::npos && endBracket + 1 < text.size()
-                && text[endBracket + 1] == '(')
+            if (endBracket != std::string_view::npos && endBracket + 1 < text.size() && text[endBracket + 1] == '(')
             {
                 auto const endParen = text.find(')', endBracket + 2);
                 if (endParen != std::string_view::npos)