Skip to content

zdrgeo/osmium

BranchesTags

Repository files navigation

Osmium

This is a prototype tool for exploring the dependencies between elements in a software system module by analyzing the evolution of the source files that contain these elements.

Overview

Osmium uses the DSM (Design Structure Matrix) methods to measure and visualize the cohession between files in a GitHub repository by tracking how often these files were changed together in a logical units like Git commits or GitHub pull requests. Each number in the matrix represents the number of times the X-axis file was changed along with the Y-axis file in the same commit or pull request. Osmium is implemented as a CLI application with commands for generating analyses and building different views (presentations) on them. It is also available as a GitHub CLI extension.

Analysis View in terminal

Analysis View in Terminal

Analysis View in web browser

Analysis View in Web Browser

Quick start

Analyse Dapr GitHub repository. Store the generated analysis model to the user home directory under the name "dapr". Be patient - this operation may take several minutes to complete.

osmium analysis github create \
    --analysis-name="dapr" \
    --repository-owner="dapr" \
    --repository-name="dapr" \
    --change="pullrequest" \
    --change-option="after=0,until=100"

Generate a view scoped to the "*.proto" files in the "dapr" directory and the "*.go" files in the "cmd", "pkg" and "utils" directories. Store the generated view model to the user home directory under the name "dapr".

osmium view create \
    --analysis-name="dapr" \
    --view-name="dapr" \
    --node-name="^dapr(/[^/]+)*/[^/]+\.proto$" \
    --node-name="^cmd(/[^/]+)*/[^/]+\.go$" \
    --node-name="^pkg(/[^/]+)*/[^/]+\.go$" \
    --node-name="^utils(/[^/]+)*/[^/]+\.go$"
    --builder="pattern"

Render to the terminal a "window" of the first 30 files of the view.

osmium view terminal render \
    --analysis-name="dapr" \
    --view-name="dapr" \
    --node-count=30

Quick Start Analysis View in Terminal (Start: 0, Count: 30)

Render to the terminal a "window" of 30 files of the view offseted 10 files to the right on the X axis. This allows for "scrolling" of the view, which often contains more files than can be displayed at once in the terminal.

osmium view terminal render \
    --analysis-name="dapr" \
    --view-name="dapr" \
    --x-node-start=10
    --node-count=30

Quick Start Analysis View in Terminal (Start: 10, Count: 30)

Generate another view scoped only to the "*.proto" files in the "dapr" directory. Store the generated view model to the user home directory under the name "api".

osmium view create \
    --analysis-name="dapr" \
    --view-name="api" \
    --node-name="^dapr(/[^/]+)*/[^/]+\.proto$"
    --builder="pattern"

Render to an HTML file the whole view and start listening for HTTP requests.

osmium view web-browser render \
    --analysis-name="dapr" \
    --view-name="api"

osmium view web-browser listen \
    --analysis-name="dapr" \
    --view-name="api"

Open http://localhost:3000/view.html in a web browser.

Quick Start Analysis View in Web Browser

Concepts

  • Analysis
  • Modules
  • Spans and Changes
  • Nodes and Edges
  • Views

The data model can be built based on data from various sources. When GitHub Pull Request source is used, Osmium iterates over all pull requests. When Git Commit source is used, Osmium iterates over all commits.

Usage

Workflow

Osmium's workflow is organized into three stages: generate an analysis, generate at least one view of the analysis, explore the views. The output of each stage is persisted and can be used mutiple times as input for the next stage. This enables iterative style of work - each stage can be repeated with the same input, but with different parameters to produce differenet outputs for the next stage. This also helps with time- and resource-intensive stages such as the analysis generation, where multiple API calls (which may also be subject of rate limits) are often required to obtain the necessary historical data from the source.

Configuration

# config.env

BASEPATH=
SOURCE=github:pullrequest
GITHUB_TOKEN=

Commands to manipulate the DSM analyses

osmium analysis github create
    --analysis-name -a
    --change -c {pullrequest}
    [--change-option -o]
    --span-size -s
    --repository-owner
    --repository-name
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--change -c pullrequest Change of the analysis - pull request.
--change-option -o Yes Options of the change. Reserved for future use.
--span-size -s Yes Size of the span.
--repository-owner Owner of the GitHub repository.
--repository-name Name of the GitHub repository. 
osmium analysis git create
    --analysis-name -a
    --change -c {commit}
    [--change-option -o]
    --span-size -s
    --repository-url
    --repository-path
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--change -c commit Change of the analysis - commit.
--change-option -o Yes Options of the change. Reserved for future use.
--span-size -s Yes Size of the span.
--repository-url URL of the Git repository.
--repository-path Path of the Git repository. 
osmium analysis github change
    --analysis-name -a
    --change -c {pullrequest}
    [--change-option -o]
    --span-size -s
    --repository-owner
    --repository-name
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--change -c pullrequest Change of the analysis - pull request.
--change-option -o Yes Options of the change. Reserved for future use.
--span-size -s Yes Size of the span.
--repository-owner Owner of the GitHub repository.
--repository-name Name of the GitHub repository. 
osmium analysis git change
    --analysis-name -a
    --change -c {commit}
    [--change-option -o]
    --span-size -s
    --repository-url
    --repository-path
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--change -c commit Change of the analysis - commit.
--change-option -o Yes Options of the change. Reserved for future use.
--span-size -s Yes Size of the span.
--repository-url URL of the Git repository.
--repository-path Path of the Git repository. 
osmium analysis delete
    --analysis-name -a
Parameter Default Optional Description
--analysis-name -a Name of the analysis.

Examples

Generate an analysis model using the GitHub repository with owner 'scaleforce' and name 'tixets' as a source. Store the generated analysis model to the user home directory under the name "ticketing_tixets".

osmium analysis github create \
    --analysis-name="ticketing_tixets" \
    --repository-owner="scaleforce" \
    --repository-name="tixets"

Alter the stored analysis model with name "ticketing_tixets". Use the same GitHub repository with owner "scaleforce" and name "tixets" as a source.

osmium analysis github change \
    --analysis-name="ticketing_tixets" \
    --repository-owner="scaleforce" \
    --repository-name="tixets"

Remove the stored analysis model with name "ticketing_tixets" from the user home directory.

osmium analysis delete \
    --analysis-name="ticketing_tixets"

Commands to manipulate the views

osmium view create
    --analysis-name -a
    --view-name -v
    [--node-name -n]
    --builder -b {filepath, pattern}
    [--builder-option -o]
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--view-name -v Name of the view.
--node-name -n Yes Names of the nodes.
--builder -b filepath Builder of the view - file path or RegExp pattern.
--builder-option -o Yes Options of the builder. Reserved for future use. 
osmium view change
    --analysis-name -a
    --view-name -v
    [--node-name -n]
    --builder -b {filepath, pattern}
    [--builder-option -o]
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--view-name -v Name of the view.
--node-name -n Yes Names of the nodes.
--builder -b filepath Builder of the view - file path or RegExp pattern.
--builder-option -o Yes Options of the builder. Reserved for future use. 
osmium view delete
    --analysis-name -a
    --view-name -v
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--view-name -v Name of the view. 
osmium view terminal render
    --analysis-name -a
    --view-name -v
    --span-name -s
    --x-node-start
    --y-node-start
    --node-count
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--view-name -v Name of the view.
--span-name -s Name of the span.
--x-node-start Start of the X nodes.
--y-node-start Start of the Y nodes.
--node-count Count of the nodes. 
osmium view web-browser render
    --analysis-name -a
    --view-name -v
    --span-name -s
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--view-name -v Name of the view.
--span-name -s Name of the span. 
osmium view web-browser listen
    --analysis-name -a
    --view-name -v
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--view-name -v Name of the view. 
osmium view csv render
    --analysis-name -a
    --view-name -v
    --span-name -s
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--view-name -v Name of the view.
--span-name -s Name of the span. 
osmium view png render
    --analysis-name -a
    --view-name -v
    --span-name -s
Parameter Default Optional Description
--analysis-name -a Name of the analysis.
--view-name -v Name of the view.
--span-name -s Name of the span.

Examples

Generate a view model based on the analysis with name "ticketing_tixets". Store the generated view model to the user home directory under the name "app". Scope the view model to nodes with names that match any of the the file paths "app/Controller/*.php", "app/Service/*.php" or "app/Repository/*.php".

osmium view create \
    --analysis-name="ticketing_tixets" \
    --view-name="app" \
    --node-name="app/Controller/*.php" \
    --node-name="app/Service/*.php" \
    --node-name="app/Repository/*.php"

Alter the stored view model with name "app" based on the analysis with name "ticketing_tixets". Scope the view to the same nodes.

osmium view change \
    --analysis-name="ticketing_tixets" \
    --view-name="app" \
    --node-name="app/Controller/*.php" \
    --node-name="app/Service/*.php" \
    --node-name="app/Repository/*.php"

Remove the stored view model with name "app" based on the analysis with name "ticketing_tixets" from the user home directory.

osmium view delete \
    --analysis-name="ticketing_tixets" \
    --view-name="app"

Render the stored view model with name "app" based on the analysis with name "ticketing_tixets" to the terminal.

osmium view terminal render \
    --analysis-name="ticketing_tixets" \
    --view-name="app"
    --x-node-start=80
    --y-node-start=20
    --node-count=40

Render the stored view model with name "app" based on the analysis with name "ticketing_tixets" to HTML file.

osmium view web-browser render \
    --analysis-name="ticketing_tixets" \
    --view-name="app"

Start serving the rendered to HTML file view model with name "app" based on the analysis with name "ticketing_tixets".

osmium view web-browser listen \
    --analysis-name="ticketing_tixets" \
    --view-name="app"

Render the stored view model with name "app" based on the analysis with name "ticketing_tixets" to CSV file.

osmium view csv render \
    --analysis-name="ticketing_tixets" \
    --view-name="app"

Render the stored view model with name "app" based on the analysis with name "ticketing_tixets" to PNG file.

osmium view png render \
    --analysis-name="ticketing_tixets" \
    --view-name="app"

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages