Address CI feedback: docs, contains(), designated initializers

- Add Doxygen comments for new public members (HardResetResult,
  UnicodeUpgradeResult, ColumnUpgradeEntry, PlanFoldingResult inner
  structs, ColumnDiff, TableDiff, RowDiff, TableDataDiff,
  DiffProgressEvent, DataSourceInfo, DriverInfo, SecretResolver move
  ops, MigrationRenderContext::ColumnKey/TableKey, SplitFileWriter
  CodeBlock).
- Replace `\ref` with backticks in SqlSchemaDiff/SqlDataDiff comments
  so doxygen stops complaining about unresolved references.
- Reword `@overload` directive in MigrationPlan.hpp so doxygen does
  not interpret the trailing words as a symbol name.
- Move `@copydoc` recursion in SqlStatement.hpp by giving the primary
  declarations their own brief docstrings.
- Exclude `src/Lightweight/tui/` from doxygen — vendored code that
  follows the upstream comment style.
- Migrate `.find(x) != std::string::npos` to `.contains(x)` (and the
  inverse) across all PR-introduced code, satisfying clang-tidy 22's
  `readability-container-contains` check.
- Convert positional aggregate initializers to designated form for
  `StatementWithComments` and `MigrationRenderContext::ColumnKey`,
  satisfying `modernize-use-designated-initializers`.

No behavioral changes — all transformations are mechanical.

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

Author: christianparpart

src/Lightweight/CodeGen/SplitFileWriter.hpp

@@ -22,7 +22,9 @@ namespace Lightweight::CodeGen
 /// migrations.
 struct CodeBlock
 {
+    /// Rendered text of the block, ready to be written verbatim into an output file.
     std::string content;
+    /// Cached newline count for `content`; reused across packing passes.
     std::size_t lineCount = 0;
 };
 

src/Lightweight/Odbc/DataSourceEnumerator.hpp

@@ -39,8 +39,10 @@ struct DataSourceInfo
         User,
         System,
     };
+    /// Whether the DSN is user-private or registered system-wide.
     Scope scope = Scope::User;
 
+    /// Total ordering on (name, description, scope) — defaulted three-way comparison.
     auto operator<=>(DataSourceInfo const&) const noexcept = default;
 };
 
@@ -54,6 +56,7 @@ struct DriverInfo
     /// Typical keys include "FileUsage", "APILevel", "ConnectFunctions".
     std::vector<std::pair<std::string, std::string>> attributes;
 
+    /// Total ordering on (name, attributes) — defaulted three-way comparison.
     auto operator<=>(DriverInfo const&) const noexcept = default;
 };
 

src/Lightweight/Secrets/SecretResolver.hpp

@@ -46,8 +46,10 @@ class LIGHTWEIGHT_API SecretResolver
     SecretResolver() = default;
     ~SecretResolver() = default;
     SecretResolver(SecretResolver const&) = delete;
+    /// Move-construct from another resolver, taking ownership of its backend chain.
     SecretResolver(SecretResolver&&) = default;
     SecretResolver& operator=(SecretResolver const&) = delete;
+    /// Move-assign from another resolver, taking ownership of its backend chain.
     SecretResolver& operator=(SecretResolver&&) = default;
 
     /// Appends a backend to the chain. The backend's `Name()` is used both as

src/Lightweight/SqlMigration.cpp

@@ -960,7 +960,8 @@ namespace
                     auto const width = CharacterWidthFromDataType(dataType, static_cast<std::size_t>(*maxLengthOpt));
                     if (width.value == 0)
                         continue;
-                    ctx.columnWidths[{ std::string(schema), std::string(table), columnName }] = width;
+                    ctx.columnWidths[MigrationRenderContext::ColumnKey {
+                        .schema = std::string(schema), .table = std::string(table), .column = columnName }] = width;
                 }
             }
             catch (SqlException const&) // NOLINT(bugprone-empty-catch) — see function comment

src/Lightweight/SqlMigration.hpp

@@ -398,8 +398,13 @@ namespace SqlMigration
             /// Per-table state: ordered column declarations + per-table FK list.
             struct TableState
             {
+                /// Ordered column declarations as they would be emitted in CREATE TABLE.
                 std::vector<SqlColumnDeclaration> columns;
+                /// Composite foreign keys declared on this table (single-column FKs are
+                /// carried inline on the corresponding `SqlColumnDeclaration::foreignKey`).
                 std::vector<SqlCompositeForeignKeyConstraint> compositeForeignKeys;
+                /// Whether the original CREATE TABLE used IF NOT EXISTS (carried through
+                /// to emitters so they can replay it verbatim).
                 bool ifNotExists = false;
             };
 
@@ -417,8 +422,11 @@ namespace SqlMigration
             /// One data step (INSERT/UPDATE/DELETE/RawSql) tagged with its source migration.
             struct DataStep
             {
+                /// Timestamp of the migration that contributed this data step.
                 MigrationTimestamp sourceTimestamp;
+                /// Title of the migration that contributed this data step.
                 std::string sourceTitle;
+                /// The plan element itself (INSERT, UPDATE, DELETE, or RawSql).
                 SqlMigrationPlanElement element;
             };
 
@@ -455,6 +463,8 @@ namespace SqlMigration
         /// @brief Result of a `HardReset` call.
         struct HardResetResult
         {
+            /// True when the populating call was a dry-run; the result describes the
+            /// would-be plan and no DDL was issued.
             bool wasDryRun = false;
             /// Tables the registered migrations *would* have created and were also present
             /// in the live DB — these were dropped (or would be dropped on a real run).
@@ -488,18 +498,23 @@ namespace SqlMigration
         /// @brief One column upgrade entry in `UnicodeUpgradeResult`.
         struct ColumnUpgradeEntry
         {
+            /// Fully-qualified name of the table that owns the column.
             SqlSchema::FullyQualifiedTableName table;
+            /// Name of the column being upgraded.
             std::string column;
             /// Live byte-counted type the column currently has.
             SqlColumnTypeDefinition liveType;
             /// Char-counted type the migrations now declare for this column.
             SqlColumnTypeDefinition intendedType;
+            /// Whether the column is nullable (preserved across the type rewrite).
             bool nullable = true;
         };
 
         /// @brief Result of an `UnicodeUpgradeTables` call.
         struct UnicodeUpgradeResult
         {
+            /// True when the populating call was a dry-run; the result describes the
+            /// would-be diff and no DDL was issued.
             bool wasDryRun = false;
             /// Columns whose live type drifted from the intended type and were upgraded
             /// (or would be on a real run).

src/Lightweight/SqlQuery/MigrationPlan.cpp

@@ -386,7 +386,8 @@ namespace
 
         for (auto& [columnName, value]: columns)
         {
-            auto const it = context.columnWidths.find({ schemaName, tableName, columnName });
+            auto const it = context.columnWidths.find(
+                MigrationRenderContext::ColumnKey { .schema = schemaName, .table = tableName, .column = columnName });
             if (it == context.columnWidths.end())
                 continue;
             std::size_t originalSize = 0;

src/Lightweight/SqlQuery/MigrationPlan.hpp

@@ -584,9 +584,10 @@ struct [[nodiscard]] MigrationRenderContext
     /// truncation layer leaves the value alone.
     struct ColumnKey
     {
-        std::string schema;
-        std::string table;
-        std::string column;
+        std::string schema; ///< Schema label (empty for engines without schemas, e.g. SQLite).
+        std::string table;  ///< Table name.
+        std::string column; ///< Column name.
+        /// Total ordering on (schema, table, column) — defaulted three-way comparison.
         auto operator<=>(ColumnKey const&) const = default;
     };
 
@@ -606,6 +607,7 @@ struct [[nodiscard]] MigrationRenderContext
         WidthUnit unit { WidthUnit::Characters };
     };
 
+    /// Cache of declared character widths, populated lazily as plan elements render.
     std::map<ColumnKey, ColumnWidth> columnWidths;
 
     /// @brief Optional fallback that fetches column widths for a `(schema, table)` from
@@ -624,10 +626,12 @@ struct [[nodiscard]] MigrationRenderContext
     /// re-query for every INSERT against the same table.
     struct TableKey
     {
-        std::string schema;
-        std::string table;
+        std::string schema; ///< Schema label (empty when the engine reports none).
+        std::string table;  ///< Table name.
+        /// Total ordering on (schema, table) — defaulted three-way comparison.
         auto operator<=>(TableKey const&) const = default;
     };
+    /// Tables for which `widthLookup` has already been called; prevents repeat queries.
     std::set<TableKey> lookupAttempted;
 
     /// @brief Identity of the migration currently being rendered. Set by
@@ -636,6 +640,7 @@ struct [[nodiscard]] MigrationRenderContext
     /// offending migration. Empty / zero when rendering happens outside a migration
     /// run (e.g. unit tests calling `ToSql` directly).
     std::string activeMigrationTitle;
+    /// Timestamp of the migration currently being rendered (0 outside a migration run).
     std::uint64_t activeMigrationTimestamp = 0;
 };
 
@@ -650,7 +655,8 @@ struct [[nodiscard]] MigrationRenderContext
 [[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> ToSql(SqlQueryFormatter const& formatter,
                                                              SqlMigrationPlanElement const& element);
 
-/// @overload Rendering variant that consults a `MigrationRenderContext` for compat flags
+/// @overload
+/// Rendering variant that consults a `MigrationRenderContext` for compat flags
 /// and column-width tracking. Updates `context` in place when the rendered step declares
 /// new columns.
 [[nodiscard]] LIGHTWEIGHT_API std::vector<std::string> ToSql(SqlQueryFormatter const& formatter,

src/Lightweight/SqlStatement.hpp

@@ -224,13 +224,24 @@ class [[nodiscard]] SqlStatement final: public SqlDataBinderCallback
         std::source_location location = std::source_location::current()) noexcept;
     void CloseCursor() noexcept;
 
+    /// @brief Binds the given output column variables to the result columns of this statement.
+    /// @tparam Args ODBC-bindable output column types.
+    /// @param args Pointers to caller-owned storage for each result column, in order.
     template <SqlOutputColumnBinder... Args>
     void BindOutputColumns(Args*... args);
 
+    /// @brief Binds the members of @p records to the result columns of this statement
+    /// in declaration order, via reflection.
+    /// @tparam Records Aggregate record types whose members map to result columns.
+    /// @param records Pointers to caller-owned record instances.
     template <typename... Records>
         requires(((std::is_class_v<Records> && std::is_aggregate_v<Records>) && ...))
     void BindOutputColumnsToRecord(Records*... records);
 
+    /// @brief Binds a single output column variable to the result column at @p columnIndex.
+    /// @tparam T An ODBC-bindable output column type.
+    /// @param columnIndex 1-based result column index.
+    /// @param arg Pointer to caller-owned storage for the column value.
     template <SqlOutputColumnBinder T>
     void BindOutputColumn(SQLUSMALLINT columnIndex, T* arg);
 
@@ -637,7 +648,7 @@ inline LIGHTWEIGHT_FORCE_INLINE std::string const& SqlStatement::PreparedQuery()
     return m_preparedQuery;
 }
 
-/// @copydoc SqlStatement::BindOutputColumns
+/// @brief Out-of-line definition of `SqlStatement::BindOutputColumns`.
 template <SqlOutputColumnBinder... Args>
 inline LIGHTWEIGHT_FORCE_INLINE void SqlStatement::BindOutputColumns(Args*... args)
 {
@@ -663,7 +674,7 @@ void SqlStatement::BindOutputColumnsToRecord(Records*... records)
      ...);
 }
 
-/// @copydoc SqlStatement::BindOutputColumn
+/// @brief Out-of-line definition of `SqlStatement::BindOutputColumn`.
 template <SqlOutputColumnBinder T>
 inline LIGHTWEIGHT_FORCE_INLINE void SqlStatement::BindOutputColumn(SQLUSMALLINT columnIndex, T* arg)
 {

src/tests/ConfigProfileStoreTests.cpp

@@ -178,7 +178,7 @@ TEST_CASE("ProfileStore — malformed YAML returns a readable error", "[ProfileS
     ScopedTempYaml const yaml("profiles:\n  broken: [not-a-map]\n");
     auto const result = Lightweight::Config::ProfileStore::LoadOrDefault(yaml.Path());
     REQUIRE_FALSE(result.has_value());
-    CHECK(result.error().find("broken") != std::string::npos);
+    CHECK(result.error().contains("broken"));
 }
 
 TEST_CASE("ProfileStore — dsn and connectionString are mutually exclusive", "[ProfileStore]")
@@ -190,8 +190,8 @@ TEST_CASE("ProfileStore — dsn and connectionString are mutually exclusive", "[
 )");
     auto const result = Lightweight::Config::ProfileStore::LoadOrDefault(yaml.Path());
     REQUIRE_FALSE(result.has_value());
-    CHECK(result.error().find("dsn") != std::string::npos);
-    CHECK(result.error().find("connectionString") != std::string::npos);
+    CHECK(result.error().contains("dsn"));
+    CHECK(result.error().contains("connectionString"));
 }
 
 TEST_CASE("ProfileStore — Remove clears default when it points at the removed profile", "[ProfileStore]")

src/tests/Lup2DbtoolTests.cpp

@@ -295,7 +295,7 @@ TEST_CASE("ResolvePositionalInserts substitutes real column names", "[lup2dbtool
         c.tableName = "cfg";
         c.columns.push_back({ .name = "nr", .type = "integer" });
         c.columns.push_back({ .name = "val", .type = "integer" });
-        m1.statements.push_back({ {}, c });
+        m1.statements.push_back({ .comments = {}, .statement = c });
     }
 
     ParsedMigration m2;
@@ -306,7 +306,7 @@ TEST_CASE("ResolvePositionalInserts substitutes real column names", "[lup2dbtool
         i.tableName = "cfg";
         i.columnValues.emplace_back("0", "4");
         i.columnValues.emplace_back("1", "215");
-        m2.statements.push_back({ {}, i });
+        m2.statements.push_back({ .comments = {}, .statement = i });
     }
 
     std::vector migrations { m1, m2 };
@@ -328,21 +328,21 @@ TEST_CASE("ResolvePositionalInserts tracks ALTER TABLE ADD COLUMN", "[lup2dbtool
         CreateTableStmt c;
         c.tableName = "t";
         c.columns.push_back({ .name = "id", .type = "integer" });
-        m.statements.push_back({ {}, c });
+        m.statements.push_back({ .comments = {}, .statement = c });
     }
     {
         AlterTableAddColumnStmt a;
         a.tableName = "t";
         a.column.name = "extra";
         a.column.type = "integer";
-        m.statements.push_back({ {}, a });
+        m.statements.push_back({ .comments = {}, .statement = a });
     }
     {
         InsertStmt i;
         i.tableName = "t";
         i.columnValues.emplace_back("0", "1");
         i.columnValues.emplace_back("1", "99");
-        m.statements.push_back({ {}, i });
+        m.statements.push_back({ .comments = {}, .statement = i });
     }
 
     std::vector migrations { m };
@@ -361,14 +361,14 @@ TEST_CASE("ResolvePositionalInserts leaves out-of-bounds indices untouched", "[l
         CreateTableStmt c;
         c.tableName = "t";
         c.columns.push_back({ .name = "id", .type = "integer" });
-        m.statements.push_back({ {}, c });
+        m.statements.push_back({ .comments = {}, .statement = c });
     }
     {
         InsertStmt i;
         i.tableName = "t";
         i.columnValues.emplace_back("0", "1");
         i.columnValues.emplace_back("1", "bogus"); // Table has only 1 column.
-        m.statements.push_back({ {}, i });
+        m.statements.push_back({ .comments = {}, .statement = i });
     }
 
     std::vector migrations { m };
@@ -525,8 +525,8 @@ TEST_CASE("ParseSqlStatement.Update.ExistsSubqueryIsStructured", "[lup2dbtool]")
     REQUIRE(std::holds_alternative<UpdateStmt>(stmt));
     auto const& u = std::get<UpdateStmt>(stmt);
     CHECK(u.tableName == "docs");
-    CHECK(u.whereExpression.find("EXISTS (") != std::string::npos);
-    CHECK(u.whereExpression.find(R"("FOLDER" IS NULL)") != std::string::npos);
+    CHECK(u.whereExpression.contains("EXISTS ("));
+    CHECK(u.whereExpression.contains(R"("FOLDER" IS NULL)"));
 }
 
 TEST_CASE("ParseSqlStatement.Update.WhereIsNull", "[lup2dbtool]")
@@ -913,24 +913,24 @@ TEST_CASE("GeneratePluginCMake.UsesPluginName", "[lup2dbtool]")
     auto const script = out.str();
 
     // Plugin name appears everywhere a target name would: add_library, GLOB variable, link, properties.
-    CHECK(script.find("add_library(MyMigrations MODULE") != std::string::npos);
-    CHECK(script.find("target_link_libraries(MyMigrations PRIVATE Lightweight::Lightweight") != std::string::npos);
-    CHECK(script.find("${MyMigrations_MIGRATIONS}") != std::string::npos);
+    CHECK(script.contains("add_library(MyMigrations MODULE"));
+    CHECK(script.contains("target_link_libraries(MyMigrations PRIVATE Lightweight::Lightweight"));
+    CHECK(script.contains("${MyMigrations_MIGRATIONS}"));
     // Plugin.cpp is the entry point the script must compile alongside the generated sources.
-    CHECK(script.find("Plugin.cpp") != std::string::npos);
+    CHECK(script.contains("Plugin.cpp"));
     // CONFIGURE_DEPENDS glob keeps lup_*.cpp additions cheap.
-    CHECK(script.find("CONFIGURE_DEPENDS") != std::string::npos);
-    CHECK(script.find("lup_*.cpp") != std::string::npos);
+    CHECK(script.contains("CONFIGURE_DEPENDS"));
+    CHECK(script.contains("lup_*.cpp"));
     // Output destination matches the existing plugin convention.
-    CHECK(script.find("${CMAKE_BINARY_DIR}/plugins") != std::string::npos);
+    CHECK(script.contains("${CMAKE_BINARY_DIR}/plugins"));
 }
 
 TEST_CASE("GeneratePluginCMake.DefaultPluginName", "[lup2dbtool]")
 {
     std::ostringstream out;
     CodeGenerator::GeneratePluginCMake(out, "LupMigrations");
     auto const script = out.str();
-    CHECK(script.find("add_library(LupMigrations MODULE") != std::string::npos);
+    CHECK(script.contains("add_library(LupMigrations MODULE"));
 }
 
 TEST_CASE("GeneratePluginEntryPoint.DeclaresPluginMacro", "[lup2dbtool]")
@@ -939,8 +939,8 @@ TEST_CASE("GeneratePluginEntryPoint.DeclaresPluginMacro", "[lup2dbtool]")
     CodeGenerator::GeneratePluginEntryPoint(out);
     auto const src = out.str();
 
-    CHECK(src.find("#include <Lightweight/SqlMigration.hpp>") != std::string::npos);
-    CHECK(src.find("LIGHTWEIGHT_MIGRATION_PLUGIN()") != std::string::npos);
+    CHECK(src.contains("#include <Lightweight/SqlMigration.hpp>"));
+    CHECK(src.contains("LIGHTWEIGHT_MIGRATION_PLUGIN()"));
 }
 
 // ================================================================================================
@@ -1019,7 +1019,7 @@ TEST_CASE("ParseSqlFile.AutoMode.PassesThroughUtf8", "[lup2dbtool]")
     // The byte payload should still contain the original UTF-8 bytes, untouched.
     bool foundUtf8 = false;
     for (auto const& [_, value]: stmt.columnValues)
-        if (value.find("\xC3\xA4") != std::string::npos)
+        if (value.contains("\xC3\xA4"))
             foundUtf8 = true;
     CHECK(foundUtf8);
     RemoveQuiet(path);
@@ -1040,9 +1040,9 @@ TEST_CASE("ParseSqlFile.AutoMode.ConvertsWindows1252", "[lup2dbtool]")
     bool foundLatin1 = false;
     for (auto const& [_, value]: stmt.columnValues)
     {
-        if (value.find("\xC3\xA4") != std::string::npos)
+        if (value.contains("\xC3\xA4"))
             foundUtf8 = true;
-        if (value.find('\xE4') != std::string::npos && value.find("\xC3\xA4") == std::string::npos)
+        if (value.contains('\xE4') && !value.contains("\xC3\xA4"))
             foundLatin1 = true;
     }
     CHECK(foundUtf8);
@@ -1072,8 +1072,8 @@ TEST_CASE("ParseSqlFile.ExplicitUtf8RejectsWindows1252", "[lup2dbtool]")
     auto const result = ParseSqlFile(path, ParserConfig { .inputEncoding = "utf-8" });
     REQUIRE_FALSE(result.has_value());
     INFO("Error message: " << result.error());
-    CHECK(result.error().find("invalid UTF-8") != std::string::npos);
-    CHECK(result.error().find("utf-8") != std::string::npos);
+    CHECK(result.error().contains("invalid UTF-8"));
+    CHECK(result.error().contains("utf-8"));
     RemoveQuiet(path);
 }
 
@@ -1085,7 +1085,7 @@ TEST_CASE("ParseSqlFile.ExplicitWindows1252RejectsUtf8", "[lup2dbtool]")
     auto const path = WriteTempSqlFile("9_99_05", "INSERT INTO T VALUES (1, 'M\xC3\xA4ller')\n");
     auto const result = ParseSqlFile(path, ParserConfig { .inputEncoding = "windows-1252" });
     REQUIRE_FALSE(result.has_value());
-    CHECK(result.error().find("validates as UTF-8") != std::string::npos);
+    CHECK(result.error().contains("validates as UTF-8"));
     RemoveQuiet(path);
 }