## Welcome

**P42** is a JavaScript and TypeScript code scanner. It analyzes your GitHub repositories to provide code modernization and refactoring suggestions.

With P42, you can:

1. Identify areas of your JavaScript and TypeScript codebase that can be refactored and modernized,
1. Get automated code reviews for your pull requests that identify possible refactorings, and
1. Apply refactorings to files and folders in bulk (using the [P42 JS Assistant for VS Code](https://marketplace.visualstudio.com/items?itemName=p42ai.refactor)).

> 💡&nbsp;&nbsp;P42 is particularly useful for teams of developers who need to modernize a codebase or work with legacy JavaScript code.

## 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/p42-for-github/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/p42-for-github/repository-page#elements).

### File Size

The maximum file size for source code files is 512 KB. Files that are larger than 512 KB will not be analyzed.

### Diff Size Per File

The maximum raw diff data for a file is 256 KB. The source file will not be analyzed if the diff size exceeds 256 KB.

## Supported Languages

Currently P42 supports the following languages and file types:

1. JavaScript (.js, .jsx, .mjs, .cjs)
1. TypeScript (.ts, .tsx, .mts, .cts)

> 📝&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/p42-for-github/how-p42-works) for more information.

## Navigation

The P42 interface features a simple top navigation bar containing the following elements:

+ <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/p42-for-github/get-started/p42-help.png) - Help link. Takes you to the documentation for the current
  page.
+ ![P42 logout](/image/documentation/p42-for-github/get-started/p42-logout.png) - Sign out button. Ends the current P42 session.
+ **Repositories** - Go to the [Repositories Page](/documentation/p42-for-github/repositories-page) for your P42 account.

Welcome

Requirements

Limits and Boundaries

Supported Languages

Workflow

Navigation

Get Started with P42 for GitHub

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

- Manage your [Repository](/documentation/p42-for-github/repository-page) settings,
- Let P42 (automatically) perform an analysis of your codebase, and
- [Review the refactoring and modernization suggestion details](/documentation/p42-for-github/repository-page#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

To get started, [sign up](/p42-for-github) 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. You can [review each suggested change](/documentation/p42-for-github/repository-page#suggestions) in a diff view. If necessary, you can [configure specific paths or folders in a repository to be excluded](/documentation/p42-for-github/repository-page#path-exclusions) during analysis.

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 concepts and workflows.

How It Works

How P42 for GitHub Works

## Sign Up and Install P42 for GitHub

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

1. Go to [p42.ai/p42-for-github](/p42-for-github) and click on **Sign Up**.
1. **Sign in** to GitHub.
1. Click on **Install P42 app**, then
    + Click **Install** (when you have only a personal account), or
    + Click to select a personal or organization account. This grants the P42 app the necessary permissions to analyze
      your code and provide suggestions.
      ![P42 install multiple repositories ](/image/documentation/p42-for-github/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.ai app access to all existing and future repositories
     associated with the GitHub account.
     ![Install P42.ai in all repositories](/image/documentation/p42-for-github/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/p42-for-github/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/p42-for-github/setup/install-p42-review-selected-repositories.png)

Once the installation is complete, P42 automatically starts the codebase analysis on all selected GitHub repositories that are not forked. For forked repositories, you need to enable the analysis on the repository page.

## 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.

Description of how to install P42 for GitHub.

Sign Up and Install P42 for GitHub

Uninstall P42 for GitHub

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/p42-for-github/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/p42-for-github/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/p42-for-github/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/p42-for-github/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/p42-for-github/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/p42-for-github/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/p42-for-github/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 for GitHub repositories page.

Elements

Configure P42 for GitHub 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 see the suggestions (if any) from the analysis.

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

## Elements

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

1. **Organization or user name**
   Links to the organization or user repositories page. For example, `user-a/`.

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

1. **Analysis status**
   Indicates if the analysis is running or pending. When the analysis is finished, the suggestion count is shown. For example, `21 suggestions`.
   > 💡&nbsp;&nbsp;If you see the "Analysis timed out" status, this means the analysis runtime for the repository has [exceeded ten minutes](/documentation/p42-for-github/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 [path exclusions](/documentation/p42-for-github/repository-page#path-exclusions) on how to do this.

1. **Enable/disable analysis**
   Indicates if the P42 analysis is enabled for this repository. Enabled by default for non-forked repositories. Click to toggle.

1. **Enable/disable code review**
   Indicates if [automated code review](/documentation/p42-for-github/code-review) is enabled for this repository. Enabled by default for new repositories. Click to toggle.

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

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

1. **Default repository branch**
   Indicates the default branch for the repository. For example, the default branch for `user-a/sample-repository` is the `main` branch.

1. **Suggestions** (tab)
   The suggestions tab contains the suggestions for the repository. See [suggestions](/documentation/p42-for-github/repository-page#suggestions) for more information.

1. **Configuration** (tab)
   The configuration tab contains the code action configurations for this repository. See [configuration](/documentation/p42-for-github/repository-page#configuration).

## 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/p42-for-github/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/p42-for-github/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.

## Suggestions

The suggestions tab contains the refactoring and modernization suggestions identified by P42 for your GitHub repository during the codebase analysis.

> 💡&nbsp;&nbsp;P42 codebase analysis works best on source files that use code formatters, such as [Prettier](https://prettier.io/).

![Suggestions tab](/image/documentation/p42-for-github/repository-page/repository-page-suggestions.png)

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

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

1. **File**
   A file for which P42 has found refactoring and modernization suggestions. For example, `packages/vega-canvas/src/domCanvas.js`

1. **Expand and Collapse**
   button ![Click to expand and view the details of the P42 suggestions for the source file](/image/documentation/p42-for-github/repository-page/suggestions-icons-expand.png) ![Click to collapse and hide the details of the P42 suggestions for the source file](/image/documentation/p42-for-github/repository-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. **View source file**
   button ![Click to view the full source file in GitHub](/image/documentation/p42-for-github/repository-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. **Suggestion**
   A suggestion that was found at a specific line number. Click to expand and see potential safety warnings and a detailed diff view.

1. **Diff view**
   The diff view shows the suggestion change in a before/after view.

## Configuration

The configuration tab contains the different code actions and their configuration for the repository.

![Configuration tab](/image/documentation/p42-for-github/repository-page/repository-page-configuration.png)

For each code action, there are several UI elements:

1. **Enabled / Disabled**
   Indicates whether this code action is enabled for the repository. Click to toggle enabled/disabled.

1. **Code Review Hint / Blocker**
   Indicates whether suggestions for this code action lead to a [P42 code review](/documentation/p42-for-github/code-review) check failure.
   Code review hints (default) do not fail checks.
   Code review blockers fail checks.
   Click to toggle enabled/disabled.

1. **Learn more**
   Link to the [code action documentation](/documentation/code-assist/) for the specific action.

1. **Short summary**
   Description of the code action in 1-2 sentences.

Path Exclusions

Suggestions

Configuration

Repository Page

When [code review is enabled](/documentation/p42-for-github/repository-page#elements), 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.

The P42 code review suggests opportunities to apply the enabled [P42 code actions](/documentation/code-assist/). Code reviews are represented as GitHub checks.

## Code Review Status

The final result of a code review (success, neutral, or failure) depends on the found suggestions and the [code review setting of the code actions](/documentation/p42-for-github/repository-page#configuration) (hint vs. blocker):

+ **Success**: P42 has no suggestions.
+ **Neutral**: P42 has suggestions in hint code actions. P42 has no suggestions in blocker code actions. Neutral results do not fail the overarching GitHub check.
+ **Failure**: P42 has suggestions in blocker code actions. P42 might also have suggestions in hint code actions.

> 📝&nbsp;&nbsp;You need to set code actions to blockers in the [code review setting](/documentation/p42-for-github/repository-page#configuration) to make P42 mark your pull requests as failures.

While a code review is running, the check is shown as pending or in progress.

## Pull Request Reviews

When code review is enabled for a repository, P42 performs code analysis for enabled code actions whenever pull requests are created or updated.

> 📝&nbsp;&nbsp;P42 code reviews for pull requests are limited to the files that have been added or changed in the pull request.

To see the status for pull request code review:

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 (green check mark or red cross).
   ![GitHub pull request code review status indicator](/image/documentation/p42-for-github/code-review/pull-request-code-review-status.png)
1. In the checks summary popup, click on **Details** to view
   the [code review report](/documentation/p42-for-github/code-review#code-review-report).
   ![GitHub pull request code review popup](/image/documentation/p42-for-github/code-review/pull-request-code-review-popup.png)

## Default Branch Code Review

When code review is enabled for a repository, P42 performs code analysis for enabled code actions whenever commits are made to the repository's default branch.

> 📝&nbsp;&nbsp;The check status for default branch commits represents all suggestions for the default branch. The details and annotations sections of the check result are limited to suggestions for files that have been added or changed since the last scan.

To see the status for commit code reviews:

1. Navigate to your GitHub repository. For example, go to `https://github.com/UserA/sample-repository-1`.
1. Click on the check status indicator (green check mark or red cross) next to your commit hash. You should see a `P42` entry in the popup.

   ![GitHub check status indicator](/image/documentation/p42-for-github/code-review/default-branch-code-review-status.png)
1. In the checks summary popup, click on **Details** in the P42 entry to view the [code review report](/documentation/code-review#code-review-report).

   ![GitHub commit code review popup](/image/documentation/p42-for-github/code-review/default-branch-code-review-popup.png)

## Code Review Report

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

![GitHub Code Review Report](/image/documentation/p42-for-github/code-review/code-review-report.png)

1. **Suggestion Count**
   Count of how many suggestions have been found. For default branch checks, the number of 'new' suggestions that have been found since the last analysis is also shown.

1. **Code Action Overview**
   A list of P42 code actions that produced suggestions. 
   For each code action, an information/fail indicator, the name with a link to documentation, and the number of suggestions are shown.
   Additional information on the check run is shown below the list.

1. **Details**
   The details section contains all suggestions (for pull requests) or all new suggestions (for default branch checks). 
   It is sorted by code action and filename. 
   A message, an optional safety message, and a diff of the suggested change are provided for each suggestion.

1. **Annotations**
   The annotations section contains code annotations for all suggestions (for pull requests) or all new suggestions (for default branch checks). 
   For each suggestion, the annotation includes the filename, the code action, the message, an optional safety message, and a partial diff of the suggested change (under "raw output").

1. **View more details**
   A link to the scanned repository on P42.

1. **Re-run Action**
   Only available when there have been blocking suggestions. Triggers a re-run of the analysis, which can lead to different results, e.g., when code action gets disabled or changed to hint/blocker. 

## Inline Comments

P42 shows inline annotations in the changed files on your commit or pull request diffs ("Files changed" tab):

![P42 Inline Comments}](/image/documentation/p42-for-github/code-review/inline-comments.png)

For each code action suggestion, P42 creates an annotation. The annotation contains:

* The filename.
* The code action.
* The message.
* An optional safety message.
* A partial diff of the suggested change (under "raw output").

> 📝&nbsp;&nbsp;You can use the [P42 JS Assistant for VS Code](https://marketplace.visualstudio.com/items?itemName=p42ai.refactor) to comfortably update your code with the same code actions that P42 uses.


P42 for GitHub: Documentation