https://google.github.io/styleguide/intellij-java-google-style.xml

# Перевірити відповідність (не змінює файли — для CI)
./gradlew spotlessCheck

# Виправити форматування in-place (для локальної розробки)
./gradlew spotlessApply

# Перевірити тільки Java-файли
./gradlew spotlessJavaCheck

# Виправити тільки Java-файли
./gradlew spotlessJavaApply

<!-- pom.xml → <build> → <plugins> -->
<plugin>
    <groupId>com.diffplug.spotless</groupId>
    <artifactId>spotless-maven-plugin</artifactId>
    <version>3.4.0</version>

    <configuration>
        <!-- ratchetFrom: форматувати лише файли, змінені відносно origin/main -->
        <!-- <ratchetFrom>origin/main</ratchetFrom> -->

        <java>
            <!-- Цільові файли -->
            <includes>
                <include>src/main/java/**/*.java</include>
                <include>src/test/java/**/*.java</include>
            </includes>

            <!-- ── Google Java Format 1.35.0 ──────────────────────── -->
            <!-- style: GOOGLE (2-пробільний відступ, рядки до 100 символів) -->
            <!-- style: AOSP   (4-пробільний відступ, для Android-проєктів)  -->
            <googleJavaFormat>
                <version>1.35.0</version>
                <style>GOOGLE</style>
                <reflowLongStrings>true</reflowLongStrings>
                <formatJavadoc>true</formatJavadoc>
                <reorderImports>false</reorderImports>
            </googleJavaFormat>

            <!-- ── Imports ────────────────────────────────────────── -->
            <!-- '|' об'єднує групи без порожнього рядка між ними    -->
            <!-- '' — всі imports, не вказані явно                    -->
            <!-- \# — static imports                                  -->
            <importOrder>
                <order>java|javax,org,com,,\#</order>
            </importOrder>

            <!-- Видалити невикористані imports -->
            <removeUnusedImports/>

            <!-- Заборонити wildcard imports -->
            <!-- <forbidWildcardImports/> -->

            <!-- Виправити type annotations -->
            <formatAnnotations/>

            <trimTrailingWhitespace/>
            <endWithNewline/>
        </java>

        <!-- Форматування misc-файлів -->
        <formats>
            <format>
                <includes>
                    <include>pom.xml</include>
                    <include>*.md</include>
                    <include>.gitignore</include>
                    <include>.gitattributes</include>
                </includes>
                <trimTrailingWhitespace/>
                <endWithNewline/>
            </format>
        </formats>
    </configuration>

    <!-- Автоматично при mvn verify запускати spotless:check -->
    <executions>
        <execution>
            <id>spotless-check</id>
            <phase>verify</phase>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

# Перевірити (для CI — не змінює файли)
mvn spotless:check

# Виправити in-place
mvn spotless:apply

# Звичайний білд із автоматичною перевіркою (через фазу verify)
mvn verify

# Або одночасно з тестами і перевіркою форматування
mvn clean verify

// Gradle
spotless {
    ratchetFrom 'origin/main'  // перевіряти тільки файли, змінені відносно main
    // ratchetFrom 'HEAD'       // тільки uncommitted changes
    // ratchetFrom 'origin/develop'
}

<!-- Maven -->
<configuration>
    <ratchetFrom>origin/main</ratchetFrom>
</configuration>

// Gradle (за замовчуванням UTF-8)
spotless {
    encoding 'UTF-8'
}

<!-- Maven -->
<configuration>
    <encoding>UTF-8</encoding>
</configuration>

// Gradle
spotless {
    java {
        // Явно вказати цільові файли (за замовчуванням Spotless знаходить їх автоматично)
        target 'src/**/*.java'
        target 'src/main/java/**/*.java', 'src/test/java/**/*.java'

        // Виключити файли або директорії
        targetExclude 'src/generated/**', '**/BuildConfig.java'
    }
}

<!-- Maven -->
<java>
    <includes>
        <include>src/main/java/**/*.java</include>
        <include>src/test/java/**/*.java</include>
    </includes>
    <excludes>
        <exclude>src/generated/**/*.java</exclude>
    </excludes>
</java>

// Gradle — повна сигнатура з усіма параметрами
spotless {
    java {
        googleJavaFormat()                 // остання підтримувана версія (1.35.0 у 2026)
        // або з явною версією:
        googleJavaFormat('1.35.0')
            // Стиль відступу:
            .style('GOOGLE')               // 2-пробільний відступ (за замовчуванням)
            // .aosp()                     // 4-пробільний відступ (Android Open Source Project)
            //
            // Перенесення довгих рядкових літералів:
            .reflowLongStrings()           // увімкнути (за замовчуванням вимкнено)
            //
            // Форматування Javadoc:
            .formatJavadoc(true)           // true = форматувати (за замовчуванням true)
            // .skipJavadocFormatting()    // еквівалент .formatJavadoc(false)
            //
            // Перегрупування imports:
            .reorderImports(false)         // false = керувати imports через importOrder()
            // .reorderImports(true)       // GJF перегруповує imports самостійно
    }
}

<!-- Maven — повна конфігурація -->
<googleJavaFormat>
    <version>1.35.0</version>
    <!-- GOOGLE (2 пробіли) або AOSP (4 пробіли) -->
    <style>GOOGLE</style>
    <!-- Переносити довгі рядкові літерали -->
    <reflowLongStrings>true</reflowLongStrings>
    <!-- Форматувати Javadoc (true за замовчуванням) -->
    <formatJavadoc>true</formatJavadoc>
    <!-- false = imports керуємо через <importOrder> -->
    <reorderImports>false</reorderImports>
    <!-- Власний groupArtifact (не потрібно у більшості випадків) -->
    <!-- <groupArtifact>com.google.googlejavaformat:google-java-format</groupArtifact> -->
</googleJavaFormat>

// Gradle
spotless {
    java {
        eclipse()                                     // Eclipse за замовчуванням
        eclipse('4.26')                               // конкретна версія Eclipse
        eclipse().configFile('eclipse-format.xml')   // із зовнішнього файлу
    }
}

<!-- Maven -->
<eclipse>
    <version>4.26</version>
    <configFile>eclipse-format.xml</configFile>
</eclipse>

// Gradle (потребує Node.js)
spotless {
    java {
        prettier(['prettier': '3.2.5', 'prettier-plugin-java': '2.6.0'])
            .config(['tabWidth': 4, 'printWidth': 120])
    }
}

// Gradle
spotless {
    java {
        // Варіант 1: стандартний порядок Eclipse (мінімальна конфігурація)
        importOrder()

        // Варіант 2: явний порядок груп (рекомендований)
        // Кожен рядок = окрема група з порожнім рядком між ними
        // '' (порожній рядок) = "всі imports, що не потрапили у жодну групу"
        // '\\#' = static imports (import static ...)
        importOrder('java', 'javax', 'org', 'com', '', '\\#')

        // Варіант 3: об'єднання груп БЕЗ порожнього рядка між ними (через '|')
        // java та javax будуть в одній групі без роздільника
        importOrder('java|javax', 'org', 'com', '', '\\#')

        // Варіант 4: з файлу (формат Eclipse .importorder)
        importOrderFile('config/eclipse.importorder')

        // Варіант 5: static imports першими (стиль деяких Google-команд)
        importOrder('\\#', 'java', 'javax', 'org', 'com', '')
    }
}

<!-- Maven -->
<importOrder>
    <!-- Роздільник груп — кома. '|' — без порожнього рядка між групами. -->
    <!-- '\#' — static imports -->
    <order>java|javax,org,com,,\#</order>

    <!-- Або з файлу: -->
    <!-- <file>config/eclipse.importorder</file> -->
</importOrder>

# Порядок imports для Spotless / Eclipse
0=java
1=javax
2=org
3=com
4=
5=\#

// Gradle
spotless {
    java {
        // Стандартний движок (google-java-format)
        removeUnusedImports()

        // Альтернативний движок (підтримує ширший діапазон Java-версій)
        // Корисний якщо googleJavaFormat не підтримує вашу версію синтаксису
        removeUnusedImports('cleanthat-javaparser-unnecessaryimport')
    }
}

<!-- Maven -->
<removeUnusedImports/>
<!-- або з альтернативним движком: -->
<removeUnusedImports>
    <engine>cleanthat-javaparser-unnecessaryimport</engine>
</removeUnusedImports>

// Gradle
spotless {
    java {
        forbidWildcardImports()    // провалити білд при знахідці import java.util.*
    }
}

<!-- Maven -->
<forbidWildcardImports/>

// Gradle — автоматично розгорнути import java.util.* у конкретні imports
spotless {
    java {
        expandWildcardImports()
    }
}

<!-- Maven -->
<expandWildcardImports/>

// Gradle (для проєктів на Java 25+)
spotless {
    java {
        forbidModuleImports()
    }
}

<!-- Maven -->
<forbidModuleImports/>

// Gradle
spotless {
    java {
        formatAnnotations()
    }
}

<!-- Maven -->
<formatAnnotations/>

// До formatAnnotations() — некоректно
@NonNull String
getTitle() { ... }

// Після formatAnnotations() — коректно
@NonNull
String getTitle() { ... }

spotless {
    java {
        trimTrailingWhitespace()   // видалити всі trailing spaces/tabs
    }
}

spotless {
    java {
        endWithNewline()    // файл має закінчуватися '\n'
    }
}

spotless {
    format 'misc', {                 // зазвичай у misc, не у java
        leadingTabsToSpaces(2)       // замінити leading tabs на 2 пробіли
        // leadingSpacesToTabs()     // замінити leading spaces на tabs
        // leadingTabsToSpaces(4)    // замінити tabs на 4 пробіли
    }
}

// Gradle — рядковий literal
spotless {
    java {
        licenseHeader '/* Copyright (C) $YEAR Example Corp. All rights reserved. */'
        // $YEAR — автоматично підставляється рік (з git history або поточний)
    }
}

// Gradle — із зовнішнього файлу
spotless {
    java {
        licenseHeaderFile 'config/license-header.txt'
        // Або з явним роздільником (за замовчуванням Spotless визначає сам)
        licenseHeaderFile('config/license-header.txt', 'package ')
    }
}

<!-- Maven -->
<licenseHeader>
    <content>/* Copyright (C) $YEAR Example Corp. All rights reserved. */</content>
</licenseHeader>

<!-- або з файлу -->
<licenseHeader>
    <file>${project.basedir}/config/license-header.txt</file>
    <delimiter>package </delimiter>
</licenseHeader>

/*
 * Copyright (C) $YEAR Example Corp.
 *
 * Licensed under the Apache License, Version 2.0.
 */

// Gradle
spotless {
    format 'misc', {
        // Вибір файлів
        target '*.gradle', '*.md', '*.yml', '*.yaml',
               '.gitignore', '.gitattributes', '.editorconfig'

        // Виключення
        targetExclude 'build/**', '.gradle/**'

        // Кроки форматування (ті самі, що доступні у java {})
        trimTrailingWhitespace()
        endWithNewline()
        leadingTabsToSpaces(2)     // якщо yaml потребує пробілів
    }

    // Можна мати кілька форматів
    format 'xml', {
        target 'src/**/*.xml', 'config/**/*.xml'
        trimTrailingWhitespace()
        endWithNewline()
        // Для XML можна підключити prettier або eclipse XML formatter
    }
}

<!-- Maven -->
<formats>
    <format>
        <includes>
            <include>*.md</include>
            <include>*.yml</include>
            <include>.gitignore</include>
        </includes>
        <trimTrailingWhitespace/>
        <endWithNewline/>
    </format>
</formats>

// Gradle
spotless {
    java {
        cleanthat()
            // Конкретні мутатори (правила рефакторингу)
            .addMutator('UnnecessaryModifier')    // видалити зайві модифікатори
            .addMutator('StringReplaceAll')        // String.replaceAll → String.replace де можливо
            .addMutator('PrimitiveWrapperInstantiation') // new Integer(x) → Integer.valueOf(x)

        googleJavaFormat('1.35.0')  // CleanThat запускається першим, потім GJF
    }
}

<!-- Maven -->
<cleanthat>
    <mutators>
        <mutator>UnnecessaryModifier</mutator>
        <mutator>StringReplaceAll</mutator>
    </mutators>
</cleanthat>
<googleJavaFormat>
    <version>1.35.0</version>
</googleJavaFormat>

// build.gradle
plugins {
    id 'java'
    id 'com.github.spotbugs' version '6.5.1'
}

spotbugs {
    // Версія самого SpotBugs (не плагіна)
    toolVersion = '4.8.6'

    // Глибина аналізу: min, default, more, max
    // 'max' — найретельніший, але повільніший
    effort = 'max'

    // Мінімальна серйозність для повідомлення: low, medium, high
    // 'low' — показувати всі, включаючи незначні
    reportLevel = 'low'

    // false — провалити білд при знахідках (рекомендовано для CI)
    ignoreFailures = false

    // Файл виключень: паттерни помилок, які ігноруємо свідомо
    excludeFilter = file('config/spotbugs-exclude.xml')
}

// Генерувати HTML-звіт (зручніший за XML для ручного перегляду)
tasks.withType(com.github.spotbugs.snom.SpotBugsTask).configureEach {
    reports {
        html {
            required = true
            outputLocation = file("$buildDir/reports/spotbugs/${name}.html")
        }
        xml.required = false
    }
}

// Запускати SpotBugs при ./gradlew check
tasks.named('check') {
    dependsOn 'spotbugsMain'
    // dependsOn 'spotbugsTest' // за потреби аналізувати і тести
}

<?xml version="1.0" encoding="UTF-8"?>
<FindBugsFilter>
    <!-- Ігнорувати все у тест-класах -->
    <Match>
        <Class name="~.*Test" />
    </Match>
    <!-- Ігнорувати попередження стилю (залишаємо Spotless для цього) -->
    <Match>
        <Bug category="STYLE" />
    </Match>
    <!-- Ігнорувати конкретну помилку у конкретному класі -->
    <!--
    <Match>
        <Class name="com.example.audiobook.db.ConnectionManager" />
        <Bug pattern="OBL_UNSATISFIED_OBLIGATION" />
    </Match>
    -->
</FindBugsFilter>

<!-- pom.xml → <build> → <plugins> -->
<plugin>
    <groupId>com.github.spotbugs</groupId>
    <artifactId>spotbugs-maven-plugin</artifactId>
    <version>4.9.3.0</version>
    <configuration>
        <!-- Глибина аналізу -->
        <effort>Max</effort>
        <!-- Мінімальна серйозність: Low, Medium, High -->
        <threshold>Low</threshold>
        <!-- Генерувати XML звіт -->
        <xmlOutput>true</xmlOutput>
        <!-- Файл виключень -->
        <excludeFilterFile>config/spotbugs-exclude.xml</excludeFilterFile>
    </configuration>
    <executions>
        <execution>
            <goals>
                <!-- check провалює білд при знахідках -->
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

# Gradle
./gradlew spotbugsMain           # аналіз src/main/java
./gradlew spotbugsTest           # аналіз src/test/java
# Звіт: build/reports/spotbugs/main.html

# Maven
mvn spotbugs:check               # аналіз і провал при знахідках
mvn spotbugs:gui                 # відкрити GUI для перегляду результатів
mvn spotbugs:spotbugs            # лише генерація звіту без провалу
# Звіт: target/spotbugsXml.xml

# Запуск контейнера з постійним зберіганням даних
docker run -d \
  --name sonarqube \
  -p 9000:9000 \
  -v sonarqube_data:/opt/sonarqube/data \
  -v sonarqube_logs:/opt/sonarqube/logs \
  sonarqube:community

# SonarQube запускається ~30-60 секунд
# Відкрийте: http://localhost:9000
# Логін: admin / admin → обов'язково змінити пароль

// build.gradle
plugins {
    id 'java'
    id 'org.sonarqube' version '7.2.3.7755'
    id 'jacoco'           // для звіту покриття тестами
}

sonar {
    properties {
        property 'sonar.projectKey',  'audiobook-platform'
        property 'sonar.projectName', 'Audiobook Platform'
        property 'sonar.host.url',    'http://localhost:9000'

        // Токен береться зі змінної середовища SONAR_TOKEN
        // Ніколи не хардкодьте токен у build.gradle!
        property 'sonar.token', System.getenv('SONAR_TOKEN') ?: ''

        // Шлях до JaCoCo XML-звіту (для покриття тестами)
        property 'sonar.coverage.jacoco.xmlReportPaths',
                 "${buildDir}/reports/jacoco/test/jacocoTestReport.xml"

        // Виключити з аналізу генерований код
        property 'sonar.exclusions', '**/generated/**,**/*Test*.java'
    }
}

// JaCoCo: генерація звіту покриття
jacoco {
    toolVersion = '0.8.12'
}

jacocoTestReport {
    dependsOn test       // спочатку запустити тести
    reports {
        xml.required  = true   // SonarQube читає XML
        html.required = true   // для ручного перегляду
    }
}

export SONAR_TOKEN=sqp_your_token_here

# Запустити тести → сформувати JaCoCo-звіт → надіслати у SonarQube
./gradlew test jacocoTestReport sonar

<!-- pom.xml → <properties> -->
<properties>
    <sonar.projectKey>audiobook-platform</sonar.projectKey>
    <sonar.projectName>Audiobook Platform</sonar.projectName>
    <sonar.host.url>http://localhost:9000</sonar.host.url>
    <!-- Токен зі змінної середовища -->
    <sonar.token>${env.SONAR_TOKEN}</sonar.token>
    <!-- Шлях до JaCoCo XML-звіту -->
    <sonar.coverage.jacoco.xmlReportPaths>
        ${project.build.directory}/site/jacoco/jacoco.xml
    </sonar.coverage.jacoco.xmlReportPaths>
    <sonar.exclusions>**/generated/**</sonar.exclusions>
</properties>

<!-- pom.xml → <build> → <plugins> -->
<!-- JaCoCo для генерації звіту покриття тестами -->
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.12</version>
    <executions>
        <!-- Інструментує тести для збору даних покриття -->
        <execution>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <!-- Генерує звіт після виконання тестів -->
        <execution>
            <id>report</id>
            <phase>test</phase>
            <goals><goal>report</goal></goals>
        </execution>
    </executions>
</plugin>

export SONAR_TOKEN=sqp_your_token_here

# Зібрати → тести → JaCoCo → SonarQube
mvn clean verify sonar:sonar