Skip to content
This repository has been archived by the owner on Mar 8, 2024. It is now read-only.

Latest commit

 

History

History
311 lines (280 loc) · 22.2 KB

README.md

File metadata and controls

311 lines (280 loc) · 22.2 KB



Early detection of breaking changes based on API usage


Travis build status AppVeyor build status Codecov Schaap Built with love

Schaapi ensures Safe Changes for APIs of libraries. It focuses on detection of semantic breaking changes, but provides a general-purpose pipeline that is also applicable to the detection of other types of breaking changes. The default implementation detects incompatibilities between Java libraries and Java projects using that library.

Requirements and Installation

Schaapi requires JRE 8 and has been tested on Windows and Unix systems.

Usage

Run the JAR as java -jar schaapi.jar <flavor> <args> or run a local build with gradlew :application:run --args='<flavor> <args>'.

Set the system property log.level to debug to enable debug output in the log file.

Pipeline Flavor

Schaapi allows you to mine projects from different sources, such as GitHub. In particular, it recognizes two such pipeline "flavors": directory (locally sourced projects) and github (projects mined from GitHub). Each of these have their own behavior and options. Click on one of the flavors below for a list of command-line options.

Directory flavor options

usage: schaapi -o <arg> [--delete_old_output] -l <arg>
       [--skip_user_compile] [--maven_dir <arg>] [--repair_maven] -u <arg>
       [--library_type <arg>] [--user_compile_timeout <arg>]
       [--pattern_detector_minimum_count <arg>]
       [--pattern_detector_maximum_sequence_length <arg>]
       [--pattern_minimum_library_usage_count <arg>]
       [--test_generator_parallel] [--test_generator_disable_output]
       [--test_generator_timeout <arg>]
 -o,--output_dir <arg>                                 The output
                                                       directory.
    --delete_old_output                                Deletes the output
                                                       directory before
                                                       running the
                                                       pipeline.
 -l,--library_dir <arg>                                The library
                                                       directory.
    --skip_user_compile                                Skip compilation of
                                                       user projects.
    --maven_dir <arg>                                  The directory to
                                                       run Maven from.
    --repair_maven                                     Repairs the Maven
                                                       installation.
 -u,--user_base_dir <arg>                              The directory
                                                       containing user
                                                       project
                                                       directories.
    --library_type <arg>                               The type of
                                                       library.
                                                       [javamaven,
                                                       javajar]
    --user_compile_timeout <arg>                       The maximum number
                                                       of seconds the
                                                       compilation of a
                                                       user project may
                                                       take. Set to 0 to
                                                       disable the
                                                       timeout.
    --pattern_detector_minimum_count <arg>             The minimum number
                                                       of occurrences for
                                                       a statement to be
                                                       considered
                                                       frequent.
    --pattern_detector_maximum_sequence_length <arg>   The maximum length
                                                       of sequences to be
                                                       considered for
                                                       pattern detection.
    --pattern_minimum_library_usage_count <arg>        The minimum number
                                                       of library usages
                                                       per method.
    --test_generator_parallel                          True if test
                                                       generator should
                                                       run in parallel.
                                                       Requires that test
                                                       generator output is
                                                       disabled.
    --test_generator_disable_output                    True if test
                                                       generator output
                                                       should be hidden.
    --test_generator_timeout <arg>                     The time limit per
                                                       pattern for the
                                                       test generator.

GitHub flavor options

usage: schaapi -o <arg> [--delete_old_output] -l <arg> [--maven_dir <arg>]
       [--repair_maven] --github_oauth_token <arg> [--max_projects <arg>]
       --library_group_id <arg> --library_artifact_id <arg>
       --library_version <arg> [--sort_by_stargazers] [--sort_by_watchers]
       [--version_verification_timeout <arg>] [--library_type <arg>]
       [--user_compile_timeout <arg>]
       [--pattern_minimum_library_usage_count <arg>]
       [--pattern_detector_minimum_count <arg>]
       [--pattern_detector_maximum_sequence_length <arg>]
       [--test_generator_parallel] [--test_generator_disable_output]
       [--test_generator_timeout <arg>]
 -o,--output_dir <arg>                                 The output
                                                       directory.
    --delete_old_output                                Deletes the output
                                                       directory before
                                                       running the
                                                       pipeline.
 -l,--library_dir <arg>                                The library
                                                       directory.
    --maven_dir <arg>                                  The directory to
                                                       run Maven from.
    --repair_maven                                     Repairs the Maven
                                                       installation.
    --github_oauth_token <arg>                         Token of GitHub
                                                       account used for
                                                       searching.
    --max_projects <arg>                               Maximum amount of
                                                       projects to
                                                       download from
                                                       GitHub.
    --library_group_id <arg>                           Group id of library
                                                       mined projects
                                                       should have a
                                                       dependency on.
    --library_artifact_id <arg>                        Artifact id of
                                                       library mined
                                                       projects should
                                                       have a dependency
                                                       on.
    --library_version <arg>                            Version of library
                                                       mined projects
                                                       should have a
                                                       dependency on.
    --sort_by_stargazers                               True if GitHub
                                                       projects should be
                                                       sorted by stars.
    --sort_by_watchers                                 True if GitHub
                                                       projects should be
                                                       sorted by watchers.
    --version_verification_timeout <arg>               The maximum number
                                                       of seconds the
                                                       verification that a
                                                       project uses the
                                                       library may take.
                                                       Set to 0 to disable
                                                       the timeout.
    --library_type <arg>                               The type of
                                                       library.
                                                       [javamaven,
                                                       javajar]
    --user_compile_timeout <arg>                       The maximum number
                                                       of seconds the
                                                       compilation of a
                                                       user project may
                                                       take. Set to 0 to
                                                       disable the
                                                       timeout.
    --pattern_minimum_library_usage_count <arg>        The minimum number
                                                       of library usages
                                                       per method.
    --pattern_detector_minimum_count <arg>             The minimum number
                                                       of occurrences for
                                                       a statement to be
                                                       considered
                                                       frequent.
    --pattern_detector_maximum_sequence_length <arg>   The maximum length
                                                       of sequences to be
                                                       considered for
                                                       pattern detection.
    --test_generator_parallel                          True if test
                                                       generator should
                                                       run in parallel.
                                                       Requires that test
                                                       generator output is
                                                       disabled.
    --test_generator_disable_output                    True if test
                                                       generator output
                                                       should be hidden.
    --test_generator_timeout <arg>                     The time limit per
                                                       pattern for the
                                                       test generator.

Library Type

Schaapi can work with different library formats. This "library type" can be one of the following: javajar (a library JAR is provided) or javamaven (the Java Maven project of that library is provided).

Pipeline Stages

1 Mining Pipeline

Stage Description
1.1 Mine Projects Mine version control or library distribution platforms for projects using your software version
1.2 Compile Projects Compile user projects
1.3 Analyse Usage per Project Create library usage graphs of user projects
1.4 Find Usage Patterns across all Projects Find common library usage patterns across usage graphs
1.5 Filter Found Patterns Filter relevant library usage patterns
1.6 Generate Tests Generate regression tests for library usage patterns

1.1 Mine Projects

Description Mine version control or library distribution platforms for projects using your software version
Interface org.cafejojo.schaapi.miningpipeline.ProjectMiner
Implementations GitHub Project Miner
Mines projects from GitHub using its code search API.
Directory Project Miner
'Mines' projects from the file system, finding all projects in one folder.

1.2 Compile Projects

Description Compile user projects
Interface org.cafejojo.schaapi.miningpipeline.ProjectCompiler
Implementations Java Maven Project Compiler
Compiles Java Maven projects, by fetching their dependencies and compiling the source code.
Java JAR Project Compiler
Compiles Java JAR projects, by inspecting the classes contained in the JAR.

1.3 Analyse Usage per Project

Description Create library usage graphs of user projects
Interface org.cafejojo.schaapi.miningpipeline.LibraryUsageGraphGenerator
Implementations Jimple Library Usage Graph Generator
Generates library usage graphs for Java using Soot Jimple control flow graphs.

1.4 Find Usage Patterns across all Projects

Description Find common library usage patterns across usage graphs
Interface org.cafejojo.schaapi.miningpipeline.PatternDetector
Implementations PrefixSpan Pattern Detector
Identifies frequent sequential patterns in graphs, using the PrefixSpan algorithm.
SPAM Pattern Detector
Identifies frequent sequential patterns in graphs, using the SPAM algorithm.
CCSpan Pattern Detector
Identifies frequent sequential patterns in graphs, using the CCSpan algorithm.

1.5 Filter Found Patterns

Description Filter relevant library usage patterns
Interface org.cafejojo.schaapi.miningpipeline.PatternFilterRule
Implementations Jimple Pattern Filters
Collection of filters that work with Soot Jimple based library usage graphs.

1.6 Generate Tests

Description Generate regression tests for library usage patterns
Interface org.cafejojo.schaapi.miningpipeline.TestGenerator
Implementations Jimple EvoSuite Test Generator
Generates testable classes based on Soot Jimple based patterns, and generates tests for those using EvoSuite.

2 Validation Pipeline

Stage Description
2.1 Execute Tests Run generated tests against a new library version
2.2 Notify Developers Notify library developer of possibly affected users

2.1 Execute Tests

Description Run generated tests against a new library version
Interface org.cafejojo.schaapi.validationpipeline.TestRunner
Implementations JUnit Test Runner
Executes a JUnit test suite and reports on the results

2.2 Notify Developers

Description Notify library developer of possibly affected users
Interface --
Implementations

Changelog

Please see releases for more information on what has changed recently.

Testing

$ ./gradlew check

Documentation

$ ./gradlew dokka

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see the license file for more information.