def combine_files(
    folder_path,
    required_columns=None,
    qualified_files=None,
    extension=".xlsx",
    source_name=None,          # ✅ Now optional — if None → no source column added
    delete_files=False,
    skip_rows=0                # ✅ Optional row skipping for Excel (e.g., skip_rows=4)
):
    """
    Combine multiple Excel files into one DataFrame with strict column checking
    and full-row duplicate removal.

    Features:
    - Missing required columns → STOP and show exact file + column.
    - If required_columns is None → keep ALL columns.
    - If qualified_files is None → combine ALL Excel files.
    - Case-insensitive + trims spaces + replaces '-' and '_' with space.
    - Duplicate rows removed based on FULL ROW match.
    - Optional row skip handling.
    - Optional 'source' column (added only if source_name is provided).
    - Prints:
        * total files combined
        * rows before removing duplicates
        * duplicate count
        * final row count
    """

    import pandas as pd
    from pathlib import Path
    import warnings

    warnings.filterwarnings("ignore", category=UserWarning, module="openpyxl")
    folder = Path(folder_path)

    # -----------------------------------------------------------
    # STEP 1: Select which files to combine
    # -----------------------------------------------------------
    if qualified_files is None:
        files_to_read = sorted([f for f in folder.iterdir() if f.suffix == extension])
    else:
        files_to_read = [folder / f for f in qualified_files]

    if not files_to_read:
        raise FileNotFoundError("No Excel files found to combine.")

    dfs = []

    # -----------------------------------------------------------
    # STEP 2: Process each file individually
    # -----------------------------------------------------------
    for file in files_to_read:

        # Read Excel with row skipping
        df = pd.read_excel(file, skiprows=skip_rows)

        # Normalize column names:
        # lowercase + trim + replace '-' and '_' with space
        df.columns = (
            df.columns
            .str.lower()
            .str.strip()
            .str.replace("-", " ")
            .str.replace("_", " ")
        )

        if required_columns is None:
            # Use ALL columns available
            selected_columns = df.columns.tolist()

        else:
            # Normalize required column names
            required_clean = [
                c.lower().strip().replace("-", " ").replace("_", " ")
                for c in required_columns
            ]

            # Missing column detection
            for req in required_clean:
                if req not in df.columns:
                    raise Exception(
                        f"\n❌ MISSING COLUMN ERROR\n"
                        f"-------------------------\n"
                        f"File:     {file.name}\n"
                        f"Missing:  '{req}'\n"
                        f"\nFix this column in the Excel file or remove this file before combining.\n"
                    )

            selected_columns = required_clean

        cleaned_df = df[selected_columns].copy()
        dfs.append(cleaned_df)

    # -----------------------------------------------------------
    # STEP 3: Combine all dataframes vertically
    # -----------------------------------------------------------
    combined = pd.concat(dfs, ignore_index=True)

    # -----------------------------------------------------------
    # STEP 4: Add 'source' column ONLY IF provided
    # -----------------------------------------------------------
    if source_name:
        combined.insert(1, "source", source_name)

    # -----------------------------------------------------------
    # STEP 5: Duplicate detection (FULL ROW matching)
    # -----------------------------------------------------------
    total_files = len(files_to_read)
    total_rows_before = len(combined)

    combined_no_dupes = combined.drop_duplicates()

    final_rows = len(combined_no_dupes)
    duplicates_removed = total_rows_before - final_rows

    print("\n📊 COMBINATION SUMMARY")
    print("----------------------------")
    print(f"Files combined:            {total_files}")
    print(f"Rows before deduplication: {total_rows_before}")
    print(f"Duplicate rows removed:    {duplicates_removed}")
    print(f"Final rows:                {final_rows}")
    print("----------------------------\n")

    # -----------------------------------------------------------
    # STEP 6: Optional delete original files
    # -----------------------------------------------------------
    if delete_files:
        for file in files_to_read:
            try:
                file.unlink()
                print(f"🗑 Deleted: {file.name}")
            except Exception as e:
                print(f"⚠ Couldn't delete {file.name}: {e}")

    return combined_no_dupes
