kicad-source/qa/tests/eeschema/test_annotation_units_integration.cpp

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#include <qa_utils/wx_utils/unit_test_utils.h>
#include "eeschema_test_utils.h"

#include <sch_reference_list.h>
#include <sch_sheet_path.h>
#include <refdes_tracker.h>

class TEST_ANNOTATION_UNITS_INTEGRATION : public KI_TEST::SCHEMATIC_TEST_FIXTURE
{
protected:
    // Helper method to create SCH_REFERENCE objects for testing
    SCH_REFERENCE createTestReference( const wxString& aRef, const wxString& aValue, int aUnit )
    {
        SCH_SYMBOL dummySymbol;
        SCH_SHEET_PATH dummyPath;

        SCH_REFERENCE ref( &dummySymbol, dummyPath );
        ref.SetRef( aRef );
        ref.SetValue( aValue );
        ref.SetUnit( aUnit );

        return ref;
    }

    // Helper method to setup units checker for testing
    void setupRefDesTracker( REFDES_TRACKER& tracker )
    {
        tracker.SetReuseRefDes( false ); // Disable reuse for these tests
        tracker.SetUnitsChecker( []( const SCH_REFERENCE& aTestRef,
                                     const std::vector<SCH_REFERENCE>& aExistingRefs,
                                     const std::vector<int>& aRequiredUnits )
        {
            // Mock implementation for unit availability check
            for( int unit : aRequiredUnits )
            {
                for( const auto& ref : aExistingRefs )
                {
                    if( ref.GetUnit() == unit
                        && ref.CompareValue( aTestRef ) == 0 )
                    {
                        return false; // Conflict found
                    }
                }
            }
            return true; // All required units are available
        } );
    }
};

struct REANNOTATED_REFERENCE
{
    wxString m_KIID;                      ///< KIID of the symbol to reannotate
    wxString m_OriginalRef;               ///< Original Reference Designator (prior to reannotating)
    wxString m_ExpectedRef;               ///< Expected Reference Designator (after reannotating)
    bool     m_IncludeInReannotationList; ///< True if reference is "selected" for reannotation
};

// Extension of the existing test fixture to test GetNextRefDesForUnits functionality
class TEST_SCH_REFERENCE_LIST_UNITS_FIXTURE : public KI_TEST::SCHEMATIC_TEST_FIXTURE
{
protected:
    void setupRefDesTracker();
    void testFindFirstUnusedReferenceWithUnits();
    void verifyUnitAvailabilityLogic();

    // Helper method to setup units checker for testing
    void setupRefDesTracker( REFDES_TRACKER& tracker )
    {
        tracker.SetUnitsChecker( []( const SCH_REFERENCE& aTestRef,
                                     const std::vector<SCH_REFERENCE>& aExistingRefs,
                                     const std::vector<int>& aRequiredUnits )
        {
            // Mock implementation for unit availability check
            for( int unit : aRequiredUnits )
            {
                for( const auto& ref : aExistingRefs )
                {
                    if( ref.GetUnit() == unit
                        && ref.CompareValue( aTestRef ) == 0 )
                    {
                        return false; // Conflict found
                    }
                }
            }
            return true; // All required units are available
        } );
    }
};

void TEST_SCH_REFERENCE_LIST_UNITS_FIXTURE::setupRefDesTracker()
{
    // Create a reference tracker with some pre-existing references
    auto tracker = std::make_shared<REFDES_TRACKER>( false );

    // Simulate previously deleted/used references
    tracker->Insert( "U1" );
    tracker->Insert( "U5" );
    tracker->Insert( "IC2" );
    tracker->Insert( "IC7" );

    m_schematic->Settings().m_refDesTracker = tracker;
}

BOOST_FIXTURE_TEST_SUITE( SchReferenceListUnits, TEST_ANNOTATION_UNITS_INTEGRATION )

struct UNIT_ANNOTATION_CASE
{
    std::string m_caseName;
    wxString    m_SchematicRelativePath;
    int         m_StartNumber;
    std::vector<REANNOTATED_REFERENCE> m_ExpectedReannotations;
    std::vector<std::string> m_PreloadedRefs; // References to preload in tracker
};

static const std::vector<UNIT_ANNOTATION_CASE> unitAnnotationCases = {
    {
        "Unit Annotation: Skip previously used references",
        "test_multiunit_reannotate",
        1,
        {
            { "cf058f25-2bad-4c49-a0c4-f059825c427f", "U99A", "U2A", true },  // Skip U1 (preloaded)
            { "e6c8127f-e282-4128-8744-05f7893bc3ec", "U99B", "U2B", true },
            { "db066797-b21c-4c1c-9591-8c7c549f8087", "U99C", "U2C", true },
        },
        { "U1" } // U1 previously used
    },
    {
        "Unit Annotation: Complex gaps with multi-unit symbols",
        "test_multiunit_reannotate_complex",
        1,
        {
            // Assuming a schematic with various multi-unit symbols
            // Where some reference numbers have been previously used
        },
        { "U1", "U3", "U7", "IC2", "IC5" }
    },
    {
        "Unit Annotation: Min value override with unit conflicts",
        "test_multiunit_reannotate",
        10, // Start at 10
        {
            { "cf058f25-2bad-4c49-a0c4-f059825c427f", "U99A", "U10A", true },
            { "e6c8127f-e282-4128-8744-05f7893bc3ec", "U99B", "U10B", true },
            { "db066797-b21c-4c1c-9591-8c7c549f8087", "U99C", "U10C", true },
        },
        { "U1", "U2", "U9" } // Various previously used refs
    }
};

BOOST_AUTO_TEST_CASE( UnitAnnotationWithRefDesTracker )
{
    for( const UNIT_ANNOTATION_CASE& c : unitAnnotationCases )
    {
        BOOST_TEST_INFO_SCOPE( c.m_caseName );

        // Skip test cases that reference non-existent schematic files
        if( c.m_SchematicRelativePath == "test_multiunit_reannotate_complex" )
        {
            BOOST_TEST_MESSAGE( "Skipping test case with non-existent schematic file" );
            continue;
        }

        try
        {
            LoadSchematic( c.m_SchematicRelativePath );

            // Setup reference tracker with preloaded references
            auto tracker = std::make_shared<REFDES_TRACKER>( false );
            for( const std::string& ref : c.m_PreloadedRefs )
            {
                tracker->Insert( ref );
            }
            m_schematic->Settings().m_refDesTracker = tracker;

            SCH_REFERENCE_LIST refsToReannotate;
            SCH_MULTI_UNIT_REFERENCE_MAP lockedRefs;

            // Build reference list for testing
            for( const REANNOTATED_REFERENCE& ref : c.m_ExpectedReannotations )
            {
                if( ref.m_IncludeInReannotationList )
                {
                    // This would need the actual symbol lookup logic from the original test
                    // For now, we'll test the concept
                    BOOST_TEST_MESSAGE( "Would test reannotation of " + ref.m_KIID.ToStdString() );
                }
            }
        }
        catch( const std::exception& e )
        {
            BOOST_TEST_MESSAGE( "Skipping test case due to missing schematic: " + std::string( e.what() ) );
        }
    }
}

BOOST_AUTO_TEST_CASE( RefDesTrackerIntegration )
{
    // Test the integration between SCH_REFERENCE_LIST and REFDES_TRACKER
    auto tracker = std::make_shared<REFDES_TRACKER>( false );

    // Preload some references
    tracker->Insert( "U1" );
    tracker->Insert( "U3" );
    tracker->Insert( "R1" );
    tracker->Insert( "R2" );
    tracker->Insert( "R5" );

    // Test GetNextRefDesForUnits respects previously inserted references
    SCH_REFERENCE uRef = createTestReference( "U", "LM358", 1 );
    std::map<int, std::vector<SCH_REFERENCE>> emptyMap;
    std::vector<int> emptyUnits;

    setupRefDesTracker( *tracker );

    int nextU = tracker->GetNextRefDesForUnits( uRef, emptyMap, emptyUnits, 1 );
    BOOST_CHECK_EQUAL( nextU, 2 ); // Should skip U1, get U2

    SCH_REFERENCE rRef = createTestReference( "R", "1k", 1 );
    int nextR = tracker->GetNextRefDesForUnits( rRef, emptyMap, emptyUnits, 1 );
    BOOST_CHECK_EQUAL( nextR, 3 ); // Should skip R1,R2, get R3

    SCH_REFERENCE icRef = createTestReference( "IC", "74HC00", 1 );
    int nextIC = tracker->GetNextRefDesForUnits( icRef, emptyMap, emptyUnits, 1 );
    BOOST_CHECK_EQUAL( nextIC, 1 ); // New prefix, should get IC1

    // Test with minimum values
    int nextU_min5 = tracker->GetNextRefDesForUnits( uRef, emptyMap, emptyUnits, 5 );
    BOOST_CHECK_EQUAL( nextU_min5, 5 ); // Should get U5 (min value 5)

    // Verify all references were inserted
    BOOST_CHECK( tracker->Contains( "U2" ) );
    BOOST_CHECK( tracker->Contains( "R3" ) );
    BOOST_CHECK( tracker->Contains( "IC1" ) );
    BOOST_CHECK( tracker->Contains( "U5" ) );
}

BOOST_AUTO_TEST_CASE( FindFirstUnusedReferenceWithUnits )
{
    // Create a reference list with some multi-unit symbols
    SCH_REFERENCE_LIST refList;
    auto tracker = std::make_shared<REFDES_TRACKER>( false );

    refList.SetRefDesTracker( tracker );

    // Test the concept of unit availability checking with GetNextRefDesForUnits

    // Test that tracker properly handles unit conflicts
    tracker->Insert( "U1" ); // Simulate U1 being previously used

    // The FindFirstUnusedReference method should now use GetNextRefDesForUnits
    // and properly consider unit conflicts when finding available references

    SCH_REFERENCE testRef = createTestReference( "U", "LM358", 1 );
    std::map<int, std::vector<SCH_REFERENCE>> emptyMap;
    std::vector<int> emptyUnits;

    setupRefDesTracker( *tracker );

    int next = tracker->GetNextRefDesForUnits( testRef, emptyMap, emptyUnits, 1 );
    BOOST_CHECK_EQUAL( next, 2 ); // Should skip U1

    BOOST_TEST_MESSAGE( "Testing unit availability concept - integrated with GetNextRefDesForUnits" );
}

BOOST_AUTO_TEST_CASE( SerializationWithComplexRefs )
{
    auto tracker = std::make_shared<REFDES_TRACKER>( false );

    // Add references through various methods
    tracker->Insert( "U1" );
    tracker->Insert( "U3" );

    // Use GetNextRefDesForUnits to get U2
    SCH_REFERENCE uRef = createTestReference( "U", "LM358", 1 );
    std::map<int, std::vector<SCH_REFERENCE>> emptyMap;
    std::vector<int> emptyUnits;

    setupRefDesTracker( *tracker );

    int next = tracker->GetNextRefDesForUnits( uRef, emptyMap, emptyUnits, 1 );
    BOOST_CHECK_EQUAL( next, 2 ); // Gets U2

    tracker->Insert( "IC1" );
    tracker->Insert( "IC5" );

    SCH_REFERENCE icRef = createTestReference( "IC", "74HC00", 1 );
    next = tracker->GetNextRefDesForUnits( icRef, emptyMap, emptyUnits, 3 );
    BOOST_CHECK_EQUAL( next, 3 ); // Gets IC3

    // Test serialization captures all state
    std::string serialized = tracker->Serialize();

    auto tracker2 = std::make_shared<REFDES_TRACKER>( false );
    BOOST_CHECK( tracker2->Deserialize( serialized ) );

    // Verify all references are preserved
    BOOST_CHECK( tracker2->Contains( "U1" ) );
    BOOST_CHECK( tracker2->Contains( "U2" ) );
    BOOST_CHECK( tracker2->Contains( "U3" ) );
    BOOST_CHECK( tracker2->Contains( "IC1" ) );
    BOOST_CHECK( tracker2->Contains( "IC3" ) );
    BOOST_CHECK( tracker2->Contains( "IC5" ) );

    // Verify next references continue correctly using GetNextRefDesForUnits
    setupRefDesTracker( *tracker2 );
    next = tracker2->GetNextRefDesForUnits( uRef, emptyMap, emptyUnits, 1 );
    BOOST_CHECK_EQUAL( next, 4 );

    next = tracker2->GetNextRefDesForUnits( icRef, emptyMap, emptyUnits, 1 );
    BOOST_CHECK_EQUAL( next, 2 );
}

BOOST_AUTO_TEST_CASE( CachingEfficiency )
{
    auto tracker = std::make_shared<REFDES_TRACKER>( false );

    // Create a scenario with many gaps to test caching
    for( int i = 1; i <= 100; i += 7 ) // Insert every 7th number
    {
        tracker->Insert( "R" + std::to_string( i ) );
    }

    SCH_REFERENCE rRef = createTestReference( "R", "1k", 1 );
    std::map<int, std::vector<SCH_REFERENCE>> emptyMap;
    std::vector<int> emptyUnits;

    setupRefDesTracker( *tracker );

    // Test that repeated calls with same parameters are fast (cached)
    auto start = std::chrono::high_resolution_clock::now();

    for( int i = 0; i < 100; ++i )
    {
        // These calls should benefit from internal caching in REFDES_TRACKER
        int result1 = tracker->GetNextRefDesForUnits( rRef, emptyMap, emptyUnits, 1 );
        int result50 = tracker->GetNextRefDesForUnits( rRef, emptyMap, emptyUnits, 50 );
    }

    auto end = std::chrono::high_resolution_clock::now();
    auto duration = std::chrono::duration_cast<std::chrono::microseconds>( end - start );

    BOOST_TEST_MESSAGE( "200 GetNextRefDesForUnits calls took: " + std::to_string( duration.count() ) + " microseconds" );

    // The actual time will vary, but the calls should complete in reasonable time
    BOOST_CHECK_LT( duration.count(), 50000 ); // Should be under 50ms for 200 calls
}

BOOST_AUTO_TEST_SUITE_END()