# Core3 Stack Visualizer Specs ## General Information This project will be created to solve the following issues: * Allow Core3 developers to view the current condition of the Core3 master build and easily find out what is currently working/broken * To navigate the different package dependencies and liabilities * Provide re-usable components and developer competence in delivering applications on the Core3 framework ## Phase I ### Login Flow The application can be accessed only by members of the Wix R&D organization through Github OAuth sign-in. This would mean registering a new OAuth application on Github. Since this is an internal app, access should be granted to wixplosives and wix-private. I'm not fully familiar with how Github has implemented OAuth2 so read up on the subject and discuss to decide the best way to implement. The following mockups depict how the login flow will look: ![Image of Login Stage 1](../design/Login-Step1.png) *Login Step 1* * if the user has already registered => go to dashboard * otherwise go to the next screen ![Image of Login Stage 2](../design/Login-Step2.png) *Login Step 2* This is a mockup of the way the Github OAuth screen looks like (it may differ today). * if the user authorizes and this action succeeds => go to dashboard * otherwise go to Login Step 1 * if cancel is an option on this screen then when clicked => go to Login Step 1 ### Dashboard * TopBar ![Image of TopBar](../design/TopBar_OpenDropDown.png) A fixed top navigation bar which includes the following components: * Logo - links to the dashboard * Application Name - *Stack Visualizer* * Page Links - centered in the top bar. Have *hover*, *click* and *active* styles * User name dropdown - The signed in user's fullname (fallback to Github username if none exists). Clicking on the arrow opens the dropdown for the *Sign Out* option. * Dashboard - Liabilities View ![Dashboard - Liabilities View](../design/Dashboard-Liabilities_View-Type_Any.png) This is the default view for users entering the application. * Packages label - *Packages* word with the number of packages currently displayed on the page (after taking in account the base number minus the packages excluded by the relevant filters) in round brackets. * Liabilities / Dependencies button bar - Has a *hover*, *click* and *active* style and no tabindex. * Filters And Ordering (see [filters](#filters-and-ordering)): * Type * Status * Order * Transitivity * Status Bar * Package List (see [package list](#package-list)) * Dashboard - Dependencies View * Dashboard States * Empty State ![Dashboard - Empty State](../design/Dashboard-Liabilities_View-Empty-State.png) * Awaiting data ![Dashboard - Spinner](../design/Dashboard-Liabilities_View-Spinner.png) Note that I'm not sure if this state will be necessary, adding this from past experience. Let's plan for it and see if needed. * Job is running on the master branch ![Dashboard - Running](../design/Dashboard-Liabilities_View-Running_build.png) Note the distinct look of a failure during job run (which is expected) * Failures after run ![Dashboard - Failure after run](../design/Dashboard-Liabilities_View-After_build_with_fail.png) ### Filters And Ordering * Type - Supports the following values: * Any type - Both internal and external packages (caption is *Type* when chosen) * Internal - The default choice, lists only internal packages * External - Lists only external packages * Status - Supports the following values: * All - Show all results, passed and failed (caption is *Status* when chosen) * Failed - Show only packages which have a liability or dependency failure * Order - Supports the following values: * Largest List - The default choice, shows results ordered by package with the largest number of liabilities/dependencies * Alphabetical - Show results ordered by name in ascending order * Place in Stack - Shown only when the non-transitive option is used * Transitive - Supports the following values: * Transitive - The default choice, show all downstream packages * Non-Transitive - Show only direct liabilities/dependencies ### Package List This sections outlines the design for the data viewed in the dashboard. Note that the information shown in this view is based on the stack.json and the errors.json files. Since there is no server in the first phase, the icon links only need to appear in this stage but do not need to be implemented (see [phase II](#phase-ii-server-side)). However, you can put the TeamCity link only on internal packages in this phase since this information is available in the stack.json file. The order by which the packages are displayed depends on the filter/order that was chosen (see [here](#liabilities-and-dependencies-logic) for a full explanation) and the type of view (liabilities or dependencies). In general, in the liabilities view you would see a package on the left and on the right all the packages which us this package. In the dependencies view all the packages on the right are those which the package on the left is depending on. ![Single Package makeup](../design/one_package.png) * Left Side Package * Package Name - A label on which the package name appears. The width of the label should be at least 22 characters in order to comfortably encompass the largest package name. The background color will change, depending on whether this package is currently in failure (in a running build or after a failed build). * Packages Info - The number of failed dependencies/liabilities, the number of successful ones and the total number of packages * Version - The current version of this package * Links: * Github link * Npm link (or sinopia if still in use) * Stack Visualizer link * TeamCity link (CIJoe) * Right Side Packages * Number of columns - **Depends** on the resolution. This should look okay on widths between 1024 and up. You should decide on a max number of columns and then center the content in the screen accordingly when it exceeds a certain size. Here's an example: ![Big Screen](../design/big_screen.png) * Specific Column - Shows the package name and underneath an annotation when relevant. Columns may be empty if there are no liabilities/dependencies. * Annotation * Liabilities View - When a failure occurs, the last version of the left-side package with which this package was successfully run will appear * Dependencies View - When a failure occurs, either the last version number will appear or the name of the first failed dependency of th failed package will appear with the last build number which was successful. See example below: ![Dependency view failure annotations](../design/Dashboard-Dependencies_View-Running_build.png) ### Packages The packages section allows the user to show information on a specific package. Navigation to this page is done through the top bar or when clicking on a specific link in the dashboard or the dependency graph. Each package should have a unique URL so that people can share them. The package page has 2 states: * Choose a package ![Choose Package closed](../design/Packages-Choose_Package_1.png) ![Choose Package closed](../design/Packages-Choose_Package_2.png) * Autocomplete * User begins entering characters and the system provides matches for the string. * Strings are only allowed for packages that exist, meaning that a user will not be able to enter a character for a package which does not exist in the list. For example - if a user enters *styloram* then only characters which match the next available characters in this phrase will be available (*stylorama*, *stylorami*) * The placeholder disappears when the user starts entering input and returns when the user deletes all input. * A package is chosen when *enter* is clicked or when the user clicks on the magnifying glass. * If the user clicks enter with an incomplete package the input should be outlined in red (invalid entry) * By default external packages are not show in the autocomplete results, however the user may choose to show them by checking the *Show external packages* checkbox. * Package page ![Package Chosen](../design/Packages-Package_Chosen.png) The package chosen view has the following sections: * Upper bar (3 labels) * Thumbnail - Clicking on *Packages* returns the user to choosing a package. The package name and current working version make up the right part of the thumbnail. * Internal/External - Label the type of package * Description - The package description (up to 2 rows), use ellipsis. * Dependencies Tree - A non-transitive list of packages (package.json) including the current version and state of the dependency (from the errors.json) * Information * Status (Failed or Passed) and the Github link to the failure * Name of last publisher on this package and when it occurred * The current version and the number of releases for this package * Links - Github, Package (npm or sinopia) when relevant, CI Link when relevant * Github Log - A list of the latest commits on Github (master) with the commit subject, author and amount of time since commit. The subject should link to the relevant Github page. Let's start with the latest 5 and later on we'll decide if we want to add more. ### Dependency Graph This section is a bonus one and should be done only outside of the sprint time. I'm just dropping the forms and you decide how you and if you want to implement it: ![Package Chosen](../design/Dependency_Graph-Choose_Package_1.png) ![Package Chosen](../design/Dependency_Graph-Choose_Package_2.png) ![Package Chosen](../design/Dependency_Graph-Package_Chosen.png) ### Remembering User Configuration & Login Core3 members should not be bothered to set the same filters and ordering they user every time. Logging in again is also not appreciated. This means that the following needs to be remembered: * Log-in access and filters/ordering should be kept an unlimited amount of time * For the liabilities and the dependencies views save the filters/order user choices and apply them the next time the page loads. ### Liabilities and Dependencies Logic ![Filter Results - Liabilities](../design/Filter_Results-Liabilities.png) *Logic behind showing the package list in the liabilities view* ![Filter Results - Dependencies](../design/Filter_Results-Dependencies.png) *Logic behind showing the package list in the dependencies view* ### Notes * Sample files are available for this project under the https://github.com/wixplosives/core3-test-stack package. @qballer will explain how to run it in CI. In order to simulate errors just pick a project and in its index.ts file add exit(1). * The design was made for a 1366x768 screen so adjust accordingly. ## Phase II - Refactor to Core3