## Welcome

**P42** is an automated, GitHub-integrated JavaScript and TypeScript code refactoring tool. It analyzes your GitHub
repositories to provide code modernization and refactoring suggestions without modifying the intended behaviour of the
code.

With P42, you can:

1. Keep your JavaScript and TypeScript codebases up-to-date with modern coding best practices,
1. Receive continuous suggestions to improve the structure, readability, and maintainability of your code, and
1. Shorten the turnaround time for GitHub pull request reviews by letting reviewers focus on the architecture and
   design, rather than code structure issues.

> 💡&nbsp;&nbsp;P42 is particularly useful for developers to efficiently update JavaScript code to newer standards to enjoy newer language features.

## Requirements

It is easy to get started with P42. All you need is a GitHub account with JavaScript (.js) and/or TypeScript (.ts)
source code in your repositories.

## Limits and Boundaries

### Repository size

The maximum GitHub repository size that can be supported is 500 MB. Any repository larger than 500 MB will not be
analyzed, and this will be indicated in the [Repositories Page](/documentation/repositories-page).

### Analysis Runtime

The maximum codebase analysis runtime for a repository is ten minutes. The analysis will automatically time out if the
runtime exceeds ten minutes. If a timeout happens, you will see the "Analysis timed out" status in
the [Repository Page](/documentation/repository-page#analysis-results).

### Diff Size Per File

The maximum raw diff data for a file is 65 kb. The source file will not be analyzed if the diff size exceeds 65 kb. This
will be indicated in the [Analysis Details](/documentation/analysis-page#analysis-details) in the Analysis page.

## Supported Languages

Currently P42 supports the following languages and file types:

1. JavaScript (.js)
1. TypeScript (.ts)

> 📝&nbsp;&nbsp;Source code files containing non-standard elements that cannot be parsed are excluded from analysis.

Everything other than the formats listed above will be skipped and excluded during analysis of a repository.

## Workflow

See [How P42 Works](/documentation/how-p42-works) for more information.

## Navigation

The P42 interface features a simple top navigation bar containing the following elements:  
![P42 top navigation bar](/image/documentation/get-started/p42-top-navigation.png)

+ <img src="/image/logo/p42_logo_no_text.svg" alt="P42 home icon" width="32"/> - Home button to get back to the [P42 homepage](/).
+ ![P42 help](/image/documentation/get-started/p42-help.png) - Help link. Takes you to the documentation for the current
  page.
+ ![P42 logout](/image/documentation/get-started/p42-logout.png) - Sign out button. Ends the current P42 session.
+ **Repositories** - Go to the [Repositories Page](/documentation/repositories-page) for your P42 account.
+ **\<GitHub_username\>/\<repository_name\>** - Quick link to return to
  the [Repository Page](/documentation/repository-page). This link is only visible when you are viewing
  the [Analysis Page](/documentation/analysis-page) for the repository. 

Welcome

Requirements

Limits and Boundaries

Supported Languages

Workflow

Navigation

Get Started

Once you have [signed up and installed P42](/documentation/setup#sign-up-and-install-p42), you can:

- Manage your [Repository](/documentation/repository-page) settings,
- Let P42 (automatically) perform an [Analysis](/documentation/analysis-page) of your codebase,
- [Review the results and analysis details](/documentation/analysis-page#analysis-details), and
- [Create a pull request](/documentation/analysis-page#pull-request) for accepted suggestions.

P42 automatically analyzes all code changes or commits made to
the [default branch of a GitHub repository](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-the-default-branch-name-for-your-repositories)
. It also analyzes all pull requests made (to all branches) in the GitHub repository.

## P42 Workflow

![P42 Workflow](/image/documentation/how-p42-works/p42-workflow.png)

To get started, [sign up to P42](/sign-up) with your GitHub account. Then log in to P42 and choose the GitHub
repositories where you want to install the P42 app. You can select public or private GitHub repositories, depending on
your [P42 plan](/pricing).

P42 automatically runs a codebase analysis on all supported file types (JavaScript and TypeScript) in your GitHub
repositories when

+ The P42 installation is complete,
+ There are code changes or commits made to the default branch of the repository, and
+ Commit checks are enabled and pull requests are made to the repository.

> ℹ️&nbsp;&nbsp;P42 codebase analysis run time depends on the number of files and complexity of the source code in each repository.

The analysis results are presented as a list of suggestions for applicable JavaScript and TypeScript source files. Code
refactoring and modernization suggestions include:

- Using template variables to replace string concatenation for better readability,
- Replacing modifiable `var` declarations with `let` and `const` blocked scope variable declarations,
- Using of arrow functions instead of the regular functions, and more.

You can [review each suggested change](/documentation/analysis-page#analysis-details) in a diff view, and decide whether
to accept or reject any or all of the suggestions. If necessary, you
can [configure specific paths or folders in a repository to be excluded](/documentation/repository-page#path-exclusions)
during analysis. Once you have reviewed all suggestions, you can easily open a pull request with all the accepted
suggestions with a single click. You can then navigate to GitHub to verify the changes and merge the pull request into
the default repository branch.

> 💡&nbsp;&nbsp;You can rename the default P42 pull request title and edit the pull request message in GitHub. See [Pull Request](/documentation/analysis-page#pull-request) for more information.

P42 automatically reruns the codebase analysis when any changes are detected in the source code (e.g. new commits), or
when new suggestions are available.

> 💡&nbsp;&nbsp;Review your P42 suggestions regularly to ensure your JavaScript and TypeScript source code stays clean, modern, and up-to-date.

Explanation of high-level P42 concepts and workflows.

How It Works

How P42 Works

## Sign Up and Install P42

To use P42, you will need to sign up with a GitHub account.

1. Go to [P42.ai](/) and click on **Sign Up Free** at the top-right of the web page.
1. Click on **Log in with GitHub** and proceed to **Sign in** with your GitHub credentials.
1. Click on **Install P42 app**, then
    + Click **Install**, or  
      ![P42 install single repository type](/image/documentation/setup/install-p42-single-repository.png)
    + Click to select a personal or organization account. This grants the P42 app the necessary permissions to analyze
      your code, provide suggestions and open pull requests.  
      ![P42 install multiple repositories ](/image/documentation/setup/install-p42-multiple-repositories.png)
1. In the Install P42.ai page, choose the GitHub repositories in which to install the P42 app.
   + **All repositories** - This options installs and grants the P42 app access to all existing and future repositories
     associated with the GitHub account.  
     ![Install P42 in all repositories](/image/documentation/setup/install-p42-all-repositories.png)
   + **Only select repositories** - Install and grant the P42 app access to specific repositories. From the **Select
     repositories** dropdown box, click to add a repository from the list. Repeat this step to add multiple
     repositories. You can click **X** to remove unwanted repositories.  
     ![Install P42 in all repositories](/image/documentation/setup/install-p42-select-specific-repositories.png)
   > ℹ️&nbsp;&nbsp;You can select public or private GitHub repositories, depending on your [P42 plan](/pricing).
1. Review your P42 configuration, and click on **Install** to proceed with the installation.  
   ![Review P42 installation settings](/image/documentation/setup/install-p42-review-selected-repositories.png)

Once the installation is complete, P42 automatically starts the codebase analysis on all selected GitHub repositories.

## Uninstall P42

To uninstall the P42 app from your GitHub account:

1. Go to the [Repositories](/repository) page. Click on **GitHub Configuration** for the account you want to uninstall
   the P42 app from.
1. In the P42 app configuration page, scroll down to the Danger zone section and click on **Uninstall**.
1. Click **OK** to confirm and proceed with uninstalling the P42 app.

Sign Up and Install P42

Uninstall P42

Setup

The **[Repositories](/repository)** page is the home page for your P42 account. This is where you can get an overview of
all repositories where the P42 app is installed.

## Elements

Here are the elements you can find in the Repositories page:

![P42 Repositories page](/image/documentation/repositories-page/repositories-page-elements.png)

1. **Configure GitHub Accounts**  
   Takes you to the Install P42.ai page to select the GitHub account you want to configure.
   See [Configure P42 App Settings](/documentation/repositories-page#configure-p42-app-settings) for more information.
1. **GitHub account**  
   GitHub account name.
1. **GitHub account type**  
   Indicates if the GitHub account is a Personal or Organization account.
1. **P42 plan**  
   [P42 plan](/pricing) for the given GitHub account.
1. **GitHub configuration**  
   Brings you to the P42 app installation page for the GitHub account, where you can uninstall or configure the P42 app.
   See [Configure P42 App Settings](/documentation/repositories-page#configure-p42-app-settings) for more information.
1. **Analysis results summary**  
   You can get a quick view of the number of suggestions resulting from the analysis of each repository. Clicking on a
   specific repository takes you to the [Repository Page](/documentation/repository-page) for a detailed breakdown of
   the refactoring and modernization suggestions.
   > 💡&nbsp;&nbsp;If you see the "Repository too large (limit is 500MB)" status, this means the repository has exceeded the maximum size supported for P42 analysis. See [Get Started - Limits and Boundaries](/documentation/get-started#limits-and-boundaries) for more information.

## Configure P42 App Settings

To change the GitHub repositories which the P42 app has access to:

1. Go to the [Repositories](/repository) page. Click on **GitHub Configuration** for the account you want to manage.  
   ![Select GitHub account to configure](/image/documentation/repositories-page/configure-p42-github-accounts.png)
1. In the P42 app configuration page, scroll down to the Repository access section.  
   ![Configure repository access for P42 app](/image/documentation/repositories-page/configure-p42-app-settings.png)
1. Choose the GitHub repositories in which to install the P42 app.
    + **All repositories** - This options installs and grants the P42 app access to all existing and future repositories
      associated with the GitHub account.
    + **Only select repositories** - Install and grant the P42 app access to specific repositories. From the **Select
      repositories** dropdown box, click to add a repository from the list, and repeat to add multiple repositories. You
      can click **X** to remove unwanted repositories.
1. Click **Save** to save the configuration changes, or click **Cancel** to undo any changes.  

Description of the P42 repositories page.

Elements

Configure P42 App Settings

Repositories Page

Each repository where the P42 app is installed has its own **Repository** page. The Repository page contains a detailed
breakdown of the refactoring and modernization suggestions specific to the repository.

To view the Repository page:

1. Log in to [P42.ai](/) and click on **Repositories**.
1. In the Repositories page, click to select a GitHub repository.
1. In the Repository page, you will get a quick view of the number of suggestions (if any) from the analysis.

> 💡&nbsp;&nbsp;Easily access the Repository page for your most important repositories by creating bookmarks in your favourite web browser.

## Elements

Here are the elements you can find in each Repository page:  
![Repository page](/image/documentation/repository-page/repository-page-elements.png)

1. **Repository name**  
   Name of the GitHub repository. For example, `UserA/sample-repository-1`.

1. **Link to GitHub repository**  
   Link to the GitHub repository. For example, `github.com/UserA/sample-repository-1`.  

1. **Excluded repository paths**  
   Brings up the **Configure Excluded Paths** dialog to
   configure [path exclusions](/documentation/repository-page#path-exclusions) for the selected repository.

1. **Default repository branch**  
   Indicates the default branch for the repository. For example, the default bran``ch for `UserA/sample-repository-1` is
   the `master` branch.

1. **Analysis Results**  
   Provides a quick view of the number of suggestions for each type of analysis for the repository, if enabled.
   See [Analysis Results](/documentation/repository-page#analysis-results) for more information.
   > 💡&nbsp;&nbsp;If you see the "Analysis timed out" status, this means the analysis runtime for the repository has [exceeded ten minutes](/documentation/get-started#analysis-runtime). You can try to resolve this error by excluding large files or folders (e.g. imported third-party libraries) from the analysis. See [Repository Page - Path Exclusions](/documentation/repository-page#path-exclusions) on how to do this.

1. **Analysis type**  
   Clicking on a type of analysis brings you to the [Analysis Page](/documentation/analysis-page).

## Path Exclusions

You can configure P42 to exclude specific paths or files in the repository from all codebase analysis and commit checks.
By default, P42 adds path exclusions for output folders (e.g. folders containing rendered output files), minimized
libraries, and third-party libraries embedded in your codebase.

To configure path exclusions:

1. Click on the **\<N\> excluded paths** button.  
   ![Click to configure the path exclusions for the repository](/image/documentation/repository-page/configure-excluded-paths.png)
1. In the **Configure Excluded Paths** dialog box, enter the prefix of the files or directories which you want to
   exclude for all P42 analysis and checks. Press the **Enter** key to specify multiple prefixes on multiple rows.  
   ![Configure Excluded Paths dialog box](/image/documentation/repository-page/configure-excluded-paths-dialog.png)
   > 📝&nbsp;&nbsp;For example, specifying `docs/` as a path prefix excludes all paths under the `docs` directory in the repository.
1. Click **Accept** to save the changes, otherwise click **Cancel** to revert to the previous settings.

## Analysis Results

Analysis Results is a summary of the code refactoring and modernization suggestions identified by P42 for your GitHub
repository during the codebase analysis.

The results from the P42 analysis would include suggestions to:

1. Use Arrow Functions,
1. Use `let` and `const` to Declare Variables,
1. Split Multi-Variable Declarations,
1. Use Template Literals,
1. Use Spread Syntax (...) instead of '.apply',
1. Use Default Parameters, and
1. Use `for...of` Loop

> 💡&nbsp;&nbsp;P42 codebase analysis works best on source files that use code formatters, such as Prettier.

You should [review the results and suggestions](/documentation/analysis-page#analysis-details) from the codebase
analysis, and proceed to [open a pull request](/documentation/analysis-page#pull-request) for accepted suggestions.

> ❗&nbsp;&nbsp;It is very important to review the accuracy of the P42 suggestions from the codebase analysis before accepting and merging a pull request. It is also recommended to run unit / integration tests post-analysis on the pull request to ensure no breaking changes result from the P42 analysis suggestions.

See [Analysis Page](/documentation/analysis-page) for more information.

Path Exclusions

Analysis Results

Repository Page

The Analysis page is the most important page in the P42 workflow. In the Analysis page, you can:

* Configure analysis and commit check settings,
* Understand the P42 approach for each suggestion category, and
* Review the suggestion details for each source file, and
* Open a pull request for accepted suggestions.

To view the Analysis page:

1. Log in to [P42.ai](/) and click on **Repositories**.
1. In the [Repositories page](/documentation/repository-page), click to select a GitHub repository.
1. In the [Repository page](/documentation/repository-page), click on a type of analysis to view the Analysis page.

## Elements

Here are the elements you can find in each Analysis page:  
![Analysis page for Using Arrow Functions](/image/documentation/analysis-page/analysis-summary-elements.png)

1. **Link to Repository page**  
   Shortcut to return to the [Repository page](/documentation/repository-page).

1. **Analysis summary**    
   This section provides a brief description of the analysis, and the type of refactoring or code modernization approach
   supported by P42.

1. **Analysis setting**  
   If this setting is enabled, P42 identifies and includes suggestions for this type of analysis for the GitHub
   repository. You can choose to disable analysis if you do not want certain modernization methods for your repository.
   When disabled, this type analysis will not be performed, and results will not be available in the Repository page.

1. **Commit checks setting**  
   You will only see this setting if Analysis is enabled. If commit checks are enabled, P42 automatically analyzes and
   provides suggestions when there are pull requests, and when new commits are made to the repository. See
   [Commit Checks](/documentation/commit-checks) for more information.

1. **Pull request**  
   You can create a new commit with all the accepted suggestions from P42 and automatically open a pull request by
   clicking the **Open Pull Request** button. See [Pull Request](/documentation/analysis-page#pull-request) for more
   information.

1. **Analysis details**  
   This is where you will find the detailed analysis results for your repository.
   See [Analysis Details](/documentation/analysis-page#analysis-details) for more information.

1. **Warnings**  
   Various types of warnings related to the analysis. P42 generates warnings if the suggested changes could potentially
   affect the semantics of the source code, or if there were source files that could not be analyzed during runtime.

## Analysis Details

This section displays the total number of suggestions and lists all the files with at least one refactoring or
modernization suggestion from P42. You should carefully review the suggestions for each file before opening a pull
request.

![Analysis Details](/image/documentation/analysis-page/suggestion-details.png)

1. **Number of suggestions**     
   Number of code refactoring or modernization suggestions based on the latest analysis of the repository.
   > 💡&nbsp;&nbsp;If you see the "Analysis timed out" status, this means the analysis runtime for the repository has [exceeded ten minutes](/documentation/get-started#analysis-runtime). You can try to resolve this error by excluding large files or folders (e.g. imported third-party libraries) from the analysis. See [Repository Page - Path Exclusions](/documentation/repository-page#path-exclusions) for details on how to do this.

1. **Not analyzed files**  
   List of source code files that could not be analyzed by P42. This could happen if the analysis runtime ten minutes
   for the repository, or if the raw data diff size for the file has exceeded 65 kb.
   See [Get Started - Limits and Boundaries](/documentation/get-started#limits-and-boundaries) for more information.

1. **Expand All**  
   Click to show the detailed code refactoring and modernization suggestions for all source files.

1. **Collapse All**  
   Click to hide the detailed code refactoring and modernization suggestions for all source files.

1. **Source files**  
   List of JavaScript / TypeScript source files with at least one suggestion resulting from the P42 analysis.

1. **Exclude suggestion**
   button ![Click to exclude the suggestion from P42 for the source file](/image/documentation/analysis-page/suggestions-icons-exclude.png)  
   Once you have reviewed the suggestions identified by P42, you can choose to accept a particular suggestion, or reject
   it clicking the exclude suggestion button next to a source file. The action to exclude the suggested changes for a
   source file becomes void if there are updated suggestions from P42, or if there are any changes (e.g. new commits) to
   the source file.

1. **View source file**
   button ![Click to view the full source file in GitHub](/image/documentation/analysis-page/suggestions-icons-view-source.png)  
   Click the view source file button next to a source file to view the original content in GitHub.

1. **Expand and Collapse**
   button ![Click to expand and view the details of the P42 suggestions for the source file](/image/documentation/analysis-page/suggestions-icons-expand.png) ![Click to collapse and hide the details of the P42 suggestions for the source file](/image/documentation/analysis-page/suggestions-icons-collapse.png)  
   Toggle the expand and collapse button next to a source file to show or hide the detailed code refactoring and
   modernization suggestions from P42 in a diff view.

1. **Diff view**  
   The diff view for a source file is similar to what you would see when making a pull request in GitHub. Original
   source code is highlighted in red, and P42-suggested changes are highlighted in green. Once you have reviewed the
   suggested changes, you can decide whether to accept the P42 suggestions (e.g. do nothing), or exclude P42 suggestions
   for the given source file when you open a pull request.

## Pull Request

### Open Pull Request

Once you have [reviewed all suggested changes](/documentation/analysis-page#analysis-details) for your repository, you
can open a pull request by clicking on the **Open Pull Request** button. This creates a new pull request containing all
the accepted P42 suggestions in a single commit.  
![Open Pull Request button in the Analysis page](/image/documentation/analysis-page/open-pull-request.png)

If the pull request is created successfully, you will see a link to the GitHub pull request, and the number of
refactoring or modernization suggestions that are included in the commit. You can navigate to GitHub to rename the
default P42 pull request title and/or edit the pull request message as necessary. Once you are satisfied with all the
committed changes, you can merge the pull request to the default branch of your repository.

### Update Pull Request

You may need to update a pull request when:

+ You exclude or re-include a suggestion from P42, or
+ Any changes are made to a source file, and not all P42 suggestions are still valid.

If a pull request needs to be updated, you will see the **Needs Update** warning. This warning tells you that the
currently-open pull request is out-of-sync with the latest suggestions from P42.
![Update an outdated pull request](/image/documentation/analysis-page/update-pull-request.png)

Once you have reviewed the new suggestions, click on the **Update Pull Request** button to commit the latest changes to
the existing pull request. Proceed to review the latest commit in GitHub accordingly.  


Analysis Details

Pull Request

Analysis Page

When [commit checks](/documentation/analysis-page#elements) are enabled, P42 analyzes and verifies code changes in the
repository whenever:

+ Pull requests are opened, or
+ Commits are made to the default branch of the GitHub repository.

## Pull Request Checks

If the commit checks setting is enabled for a type of analysis (e.g. Use Arrow Functions), P42 performs code analysis
whenever pull requests (that are not opened by the P42 app) are made to the repository.

> 📝&nbsp;&nbsp;P42 checks are only performed on files that are included in the commit for a pull request.

To check the status for pull request checks:

1. Navigate to the pull request page for your GitHub repository. For example, go
   to `https://github.com/UserA/sample-repository-1/pulls`.
1. Click on the check status indicator next to your pull request title.   
   ![GitHub pull request check status indicator](/image/documentation/commit-checks/pull-request-checks-status.png)
1. In the commit checks summary, click on **Details** to view
   the [check details](/documentation/commit-checks#check-details) page for more information on each P42 analysis
   check.  
   ![List of enabled commit checks for the pull request](/image/documentation/commit-checks/pull-request-checks-summary.png)

## Default Branch Checks

If the commit checks setting is enabled for a type of analysis (e.g. Use Arrow Functions), P42 performs the code
analysis whenever commits are made to the default branch of the repository.

> 📝&nbsp;&nbsp;P42 checks are only performed on files that are included in the commit.

To check the status for commit checks:

1. Navigate to your GitHub repository. For example, go to `https://github.com/UserA/sample-repository-1`.
1. Click on the check status indicator next to your commit hash. You should see a summary of commit checks that are
   enabled for the repository.  
   ![GitHub check status indicator](/image/documentation/commit-checks/commit-checks-status-indicator.png)
1. In the commit checks summary, click on **Details** to view
   the [checks details](/documentation/commit-checks#check-details) page for more information on each P42 analysis
   check.  
   ![List of enabled commit checks](/image/documentation/commit-checks/commit-checks-list.png)

## Check Details

You can find the following information in the GitHub checks page for your repository:

![GitHub check runs page](/image/documentation/commit-checks/commit-checks-p42-actions.png)

1. **List of P42 checks**  
   The list of P42 analysis types where the commit checks is enabled. Clicking on a type of analysis displays the
   details in the right pane.

1. **Re-run check**  
   It may be useful to re-run checks that failed or contained errors when any repository settings are changed. For
   example, if P42 suggestions are newly excluded or re-included, or if path exclusions are updated.

1. **Analysis type**  
   Type of P42 analysis.

1. **Analysis summary**  
   This section provides a brief description of the analysis, and the type of refactoring or code modernization approach
   supported by P42.

1. **Suggestions**  
   This section lists all files in the commit which failed the P42 commit check, and provides a simplified diff view on
   the P42-suggested changes for each file. 


Documentation