@jsenv/file-size-impact 14.3.29 → 14.3.31

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@jsenv/file-size-impact",
-  "version": "14.3.29",
+  "version": "14.3.31",
   "description": "Add files size impact into pull requests",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/jsenv/core",
-    "directory": "packages/independent/tooling/file-size-impact"
+    "directory": "packages/tooling/file-size-impact"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -34,9 +34,13 @@
   },
   "dependencies": {
     "@jsenv/dynamic-import-worker": "1.2.1",
-    "@jsenv/filesystem": "4.15.2",
-    "@jsenv/github-pull-request-impact": "1.8.29",
-    "@jsenv/urls": "2.7.4",
-    "@jsenv/humanize": "1.5.2"
+    "@jsenv/filesystem": "4.15.4",
+    "@jsenv/github-pull-request-impact": "1.8.31",
+    "@jsenv/urls": "2.9.0",
+    "@jsenv/humanize": "1.6.0"
+  },
+  "devDependencies": {
+    "@jsenv/assert": "../assert",
+    "@jsenv/file-size-impact": "./"
   }
 }

package/readme.md

@@ -1,17 +1,44 @@
-# File size impact
+# File Size Impact
 
 [![npm package](https://img.shields.io/npm/v/@jsenv/file-size-impact.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/file-size-impact)
 
-`@jsenv/file-size-impact` analyses a pull request impact on specific files size. This analysis is posted in a comment of the pull request on GitHub.
+`@jsenv/file-size-impact` analyzes a pull request's impact on file sizes and posts the results as a comment in your GitHub PR.
 
-- Helps you to catch size impacts before merging pull requests
-- Can be configured to track compressed file size
-- Create group of files to create meaningful reports
-- Can be added to any automated process (GitHub workflow, Jenkins, ...)
+- ✅ Catch size impacts before merging pull requests
+- 📦 Track compressed file sizes (gzip, brotli)
+- 📊 Create meaningful reports by grouping files
+- 🔄 Integrate with any CI/CD platform (GitHub Actions, Jenkins, etc.)
 
-# Pull request comment
+## Quick Start
 
-Screenshot + explanation on pull request comment.
+```console
+npm install --save-dev @jsenv/file-size-impact
+```
+
+1. Create a file size tracking script
+2. Set up your CI workflow
+3. Get size impact comments on every PR!
+
+## Table of Contents
+
+- [File Size Impact](#file-size-impact)
+  - [Quick Start](#quick-start)
+  - [Table of Contents](#table-of-contents)
+  - [Pull Request Comment](#pull-request-comment)
+  - [Installation](#installation)
+    - [Step 1: Create a file size report script](#step-1-create-a-file-size-report-script)
+    - [Step 2: Create a report script](#step-2-create-a-report-script)
+    - [GitHub Workflow](#github-workflow)
+    - [Other Tools](#other-tools)
+  - [How it Works](#how-it-works)
+  - [API Reference](#api-reference)
+    - [generateFileSizeReport](#generatefilesizereport)
+      - [Options](#options)
+    - [reportFileSizeImpactInGitHubPullRequest](#reportfilesizeimpactingithubpullrequest)
+
+## Pull Request Comment
+
+Here's how the PR comments look with explanations:
 
 ![legend of pull request comment](./docs/comment_legend.png)
 
@@ -22,17 +49,14 @@ Screenshot + explanation on pull request comment.
 | "_Unmodified (4)_"             | Sum of files in that group that are not impacted by the pull request.                                                         |
 | _Total (5)_                    | Sum of files in that group.                                                                                                   |
 
-# Installation
+## Installation
 
-The first thing you need is a script capable to generate a file size report.
+### Step 1: Create a file size report script
 
-```console
-npm install --save-dev @jsenv/file-size-impact
-```
-
-_file_size.mjs_
+First, create a script that generates your file size report:
 
 ```js
+// file_size.mjs
 import { generateFileSizeReport } from "@jsenv/file-size-impact";
 
 export const fileSizeReport = await generateFileSizeReport({
@@ -47,28 +71,34 @@ export const fileSizeReport = await generateFileSizeReport({
 });
 ```
 
-At this stage, you could generate a file size report on your machine with the following command.
+Test it locally:
 
 ```console
 node ./file_size.mjs --log
 ```
 
-Now it's time to configure a workflow to compare file size reports before and after merging a pull request.
+### Step 2: Create a report script
 
-## GitHub workflow
+```js
+// report_file_size_impact.mjs
+import {
+  reportFileSizeImpactInGitHubPullRequest,
+  readGitHubWorkflowEnv,
+} from "@jsenv/file-size-impact";
 
-_.github/workflows/file_size_impact.yml_
+await reportFileSizeImpactInGitHubPullRequest({
+  ...readGitHubWorkflowEnv(),
+  buildCommand: "npm run dist",
+  fileSizeReportUrl: new URL("./file_size.mjs#fileSizeReport", import.meta.url),
+});
+```
 
-```yml
-# This is a GitHub workflow YAML file
-# see https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
-#
-# For every push on a pull request, it
-# - starts a machine on ubuntu
-# - clone the git repository
-# - install node, install npm deps
-# - Executes report_file_size_impact.mjs
+### GitHub Workflow
 
+Create a GitHub Actions workflow file:
+
+```yml
+# .github/workflows/file_size_impact.yml
 name: file size impact
 
 on: pull_request
@@ -92,45 +122,37 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-_report_file_size_impact.mjs_
+That's it! Now your PRs will automatically get file size impact comments.
 
-```js
-/*
- * This file is executed by file_size_impact.yml GitHub workflow.
- * - it generates file size report before and after merging a pull request
- * - Then, it creates or updates a comment in the pull request
- * See https://github.com/jsenv/core/tree/main/packages/tooling/file-size-impact#how-it-works
- */
+### Other Tools
 
-import {
-  reportFileSizeImpactInGitHubPullRequest,
-  readGitHubWorkflowEnv,
-} from "@jsenv/file-size-impact";
+If you want to use another CI tool like Jenkins:
+
+1. **Create a GitHub token** with `repo` scope at https://github.com/settings/tokens/new
+2. **Update your report script** to provide environment variables:
+
+```js
+// report_file_size_impact.mjs for Jenkins
+import { reportFileSizeImpactInGitHubPullRequest } from "@jsenv/file-size-impact";
 
 await reportFileSizeImpactInGitHubPullRequest({
-  ...readGitHubWorkflowEnv(),
+  rootDirectoryUrl: process.env.WORKSPACE, // Jenkins workspace
+  repositoryOwner: process.env.GITHUB_REPO_OWNER,
+  repositoryName: process.env.GITHUB_REPO_NAME,
+  pullRequestNumber: process.env.PULL_REQUEST_NUMBER,
+  githubToken: process.env.GITHUB_TOKEN,
   buildCommand: "npm run dist",
   fileSizeReportUrl: new URL("./file_size.mjs#fileSizeReport", import.meta.url),
+  runLink: {
+    url: process.env.BUILD_URL,
+    text: `${process.env.JOB_NAME}#${process.env.BUILD_ID}`,
+  },
 });
 ```
 
-**Notes**:
+3. **Configure your CI job** to execute the necessary git commands:
 
-- "#fileSizeReport" is the name of the export from _file_size.mjs_.
-
-## Other tools
-
-If you want to use an other tool than GitHub worflow to run the pull request comparison, like Jenkins, there is a few things to do:
-
-1. Replicate _file_size_impact.yml_
-2. Adjust _report_file_size_impact.mjs_
-3. Create a GitHub token (required to post comment on GitHub)
-
-### 1. Replicate _file_size_impact.yml_
-
-Your workflow must reproduce the state where your git repository has been cloned and you are currently on the pull request branch. Something like the commands below.
-
-```console
+```shell
 git init
 git remote add origin $GITHUB_REPOSITORY_URL
 git fetch --no-tags --prune origin $PULL_REQUEST_HEAD_REF
@@ -139,74 +161,36 @@ npm install
 node ./report_file_size_impact.mjs
 ```
 
-### 2. Adjust _report_file_size_impact.mjs_
-
-When outside a GitHub workflow, you cannot use _readGitHubWorkflowEnv()_. It means you must pass several parameters to _reportFileSizeImpactInGitHubPullRequest_. The example below assume code is executed by Travis.
-
-```diff
-- import { reportFileSizeImpactInGitHubPullRequest, readGitHubWorkflowEnv } from "@jsenv/file-size-impact"
-+ import { reportFileSizeImpactInGitHubPullRequest } from "@jsenv/file-size-impact"
-
-reportFileSizeImpactInGitHubPullRequest({
-- ...readGitHubWorkflowEnv(),
-+ rootDirectoryUrl: process.env.TRAVIS_BUILD_DIR,
-+ repositoryOwner: process.env.TRAVIS_REPO_SLUG.split("/")[0],
-+ repositoryName: process.env.TRAVIS_REPO_SLUG.split("/")[1],
-+ pullRequestNumber: process.env.TRAVIS_PULL_REQUEST,
-+ githubToken: process.env.GITHUB_TOKEN, // see next step
-  buildCommand: "npm run dist",
-})
-```
-
-### 3. Create a GitHub token
+## How it Works
 
-The GitHub token is required to be able to post a commment in the pull request. You need to create a GitHub token with `repo` scope at https://github.com/settings/tokens/new. Finally you need to setup this environment variable. The exact way to do this is specific to the tools your are using.
-
-# How it works
-
-In order to analyse the impact of a pull request on file size the following steps are executed:
+The file size impact analysis follows these steps:
 
 1. Checkout pull request base branch
 2. Execute an install command (_npm install_ by default)
-3. Run a build command (nom build by default)
-4. Get a file size report (dynamic import of a js module exporting `generateFileSizeReport`)
+3. Run a build command (_npm run-script build_ by default)
+4. Generate a baseline file size report
 5. Merge pull request into its base
-6. Execute command to generate files again
-7. Get a second file size report
-8. Analyse differences between the two file size reports
-9. Post or update comment in the pull request
+6. Rebuild files
+7. Generate a second file size report
+8. Analyze differences between the two reports
+9. Post or update a comment in the pull request
 
-# generateFileSizeReport
+## API Reference
 
-_generateFileSizeReport_ is an async function scanning filesystem to compute a list of file sizes and return these infos into an object.
+### generateFileSizeReport
+
+Scans the filesystem to compute file sizes with optional transformations:
 
 ```js
-import { generateFileSizeReport, raw, gzip } from "@jsenv/file-size-impact";
+import {
+  generateFileSizeReport,
+  raw,
+  gzip,
+  brotli,
+} from "@jsenv/file-size-impact";
 
 const fileSizeReport = await generateFileSizeReport({
   rootDirectoryUrl: new URL("./", import.meta.url),
-  trackingConfig: {
-    dist: {
-      "./dist/**/*.js": true,
-    },
-  },
-  transformations: { raw, gzip },
-});
-```
-
-## trackingConfig
-
-_trackingConfig_ parameter is an object used to configure group of files you want to track. This parameter is optional with a default value exported in [src/jsenv_tracking_config.js](./src/jsenv_tracking_config.js)
-
-_trackingConfig_ keys are group names that will appear in the generated comment.
-_trackingConfig_ values are objects associating a pattern to a value.
-
-For example you can create two groups named _"critical files"_ and _"remaining files"_ like this:
-
-```js
-import { generateFileSizeReport } from "@jsenv/file-size-impact";
-
-await generateFileSizeReport({
   trackingConfig: {
     "critical files": {
       "./dist/main.js": true,
@@ -215,246 +199,35 @@ await generateFileSizeReport({
     "remaining files": {
       "./dist/**/*.js": true,
       "./dist/**/*.css": true,
-      "./dist/main.js": false,
-      "./dist/main.css": false,
+      "./dist/main.js": false, // Exclude files already in "critical files"
+      "./dist/main.css": false, // Exclude files already in "critical files"
     },
   },
-});
-```
-
-![screenshot of pull request comment where groups are highlighted](./docs/comment_group_highlighted.png)
-
-## transformations
-
-_transformations_ parameter is an object used to transform files content before computing their size. This parameter is optional with a default tracking file size without transformation called _raw_.
-
-You can use this parameter to track file size after gzip compression.
-
-```js
-import {
-  generateFileSizeReport,
-  raw,
-  gzip,
-  brotli,
-} from "@jsenv/file-size-impact";
-
-await generateFileSizeReport({
   transformations: { raw, gzip, brotli },
 });
 ```
 
-![screenshot of pull request comment with gzip and brotli](./docs/comment_compression.png)
+#### Options
 
-_raw_, _gzip_ and _brotli_ compression can be enabled this way.
+- **rootDirectoryUrl**: Project root directory (required)
+- **trackingConfig**: File groups to track (optional)
+- **transformations**: Size transformations, like compression (optional)
+- **manifestConfig**: Configuration for files with dynamic names (optional)
 
-It's also possible to control compression level.
+### reportFileSizeImpactInGitHubPullRequest
 
-```js
-import { generateFileSizeReport, raw, gzip } from "@jsenv/file-size-impact";
-
-await generateFileSizeReport({
-  transformations: {
-    raw,
-    gzip7: (buffer) => gzip(buffer, { level: 7 }),
-    gzip9: (buffer) => gzip(buffer, { level: 9 }),
-  },
-});
-```
-
-Finally _transformations_ can be used to add custom _transformations_.
-
-```js
-import {
-  generateFileSizeReport,
-  raw,
-  gzip,
-  brotli,
-} from "@jsenv/file-size-impact";
-
-await generateFileSizeReport({
-  transformations: {
-    raw,
-    trim: (buffer) => String(buffer).trim(),
-  },
-});
-```
-
-## manifestConfig
-
-_manifestConfig_ parameter is an object used to configure the location of an optional manifest file. It is used to compare [files with dynamic names](#File-with-dynamic-names). This parameter is optional with a default considering `"dist/**/manifest.json"` as manifest files.
-
-This parameter reuses the shape of [trackingConfig](#trackingConfig) (associating pattern + value).
-
-```js
-import { reportFileSizeImpactInGitHubPullRequest } from "@jsenv/file-size-impact";
-
-await reportFileSizeImpactInGitHubPullRequest({
-  manifestConfig: {
-    "./dist/**/manifest.json": true,
-  },
-});
-```
-
-You can disable manifest files handling by passing `null`.
+Analyzes PR impact and posts a comment with results:
 
 ```js
 import { reportFileSizeImpactInGitHubPullRequest } from "@jsenv/file-size-impact";
 
-await reportFileSizeImpactInGitHubPullRequest({
-  manifestConfig: {
-    "./dist/**/manifest.json": null,
-  },
-});
-```
-
-In that case _manifest.json_ will be handled as a regular file.
-
-# reportFileSizeImpactInGitHubPullRequest
-
-_reportFileSizeImpactInGitHubPullRequest_ is an async function that will analyse a pull request file size impact and post a comment with the result of this analysis.
-
-```js
-import {
-  reportFileSizeImpactInGitHubPullRequest,
-  raw,
-} from "@jsenv/file-size-impact";
-
 await reportFileSizeImpactInGitHubPullRequest({
   logLevel: "info",
-
   rootDirectoryUrl: "file:///directory",
   githubToken: "xxx",
   repositoryOwner: "jsenv",
   repositoryName: "file-size-impact",
   pullRequestNumber: 10,
-
   installCommand: "npm install",
   buildCommand: "npm run build",
-  fileSizeReportUrl: new URL("./file_size.mjs#fileSizeReport", import.meta.url),
-  filesOrdering: "size_impact",
-});
-```
-
-## logLevel
-
-_logLevel_ parameter controls verbosity of logs during the function execution. This parameter is optional with a default value of `"info"`.
-
-You likely don't need to modify this parameter except to get verbose logs using `"debug"`. The list of available values for _logLevel_ can be found on [@jsenv/logger documentation](https://github.com/jsenv/jsenv-logger#loglevel).
-
-## rootDirectoryUrl
-
-_rootDirectoryUrl_ parameter is a string leading to your project root directory. This parameter is **required**.
-
-## installCommand
-
-_installCommand_ parameter is a string representing the command to run in order to install things just after a switching to a git branch. This parameter is optional with a default value of `"npm install"`. You can pass `null` if you don't need to run an install command to run your project.
-
-## buildCommand
-
-_buildCommand_ parameter is a string representing the command to run in order to generate files. This parameter is optional with a default value of `"npm run-script build"`. You can pass `null` if you don't need to run a build command before computing file sizes.
-
-## fileSizeReportUrl
-
-_fileSizeReportUrl_ is a string or an url parameter representing an url leading a module file. This file must export a fileSizeReport produced by _generateFileSizeReport_.
-
-## filesOrdering
-
-_filesOrdering_ parameter is a string used to decide the order of the files displayed in the comment. This parameter is optional with a default value of `"size_impact"`.
-
-| filesOrdering | Description                                        |
-| ------------- | -------------------------------------------------- |
-| "size_impact" | Files are ordered by size impact                   |
-| "filesystem"  | Files are ordered as they appear on the filesystem |
-
-## runLink
-
-_runLink_ parameter allow to put a link to the workflow run in the generated comment body. It is used to indicates where file size impact was runned.
-
-![screenshot of pull request comment where runlink is highlighted](./docs/comment_run_link_highlighted.png)
-
-This parameter is returned by [readGitHubWorkflowEnv](#readGitHubWorkflowEnv) meaning it comes for free inside a GitHub workflow.
-
-Inside an other workflow, you can pass your own _runLink_. As in the example below where it is assumed that script is runned by jenkins.
-
-```js
-import { reportFileSizeImpactInGitHubPullRequest } from "@jsenv/file-size-impact";
-
-await reportFileSizeImpactInGitHubPullRequest({
-  runLink: {
-    url: process.env.BUILD_URL,
-    text: `${process.env.JOB_NAME}#${process.env.BUILD_ID}`,
-  },
-});
-```
-
-# commitInGeneratedByInfo
-
-_commitInGeneratedByInfo_ parameter is a boolean controlling if a link to the commit where size impact was performed appears in the comment. This parameter is optional and enabled by default.
-
-![screenshot of pull request comment where link to commit is highlighted](./docs/comment_commit_link_highlighted.png)
-
-# readGitHubWorkflowEnv
-
-_readGitHubWorkflowEnv_ is a function meant to be runned inside a GitHub workflow. It returns an object meant to be forwarded to [reportFileSizeImpactInGitHubPullRequest](#reportFileSizeImpactInGitHubPullRequest).
-
-```js
-import {
-  reportFileSizeImpactInGitHubPullRequest,
-  readGitHubWorkflowEnv,
-} from "@jsenv/file-size-impact";
-
-const gitHubWorkflowEnv = readGitHubWorkflowEnv();
-
-await reportFileSizeImpactInGitHubPullRequest({
-  ...gitHubWorkflowEnv,
-});
-```
-
-_gitHubWorkflowEnv_ object looks like this:
-
-```js
-const gitHubWorkflowEnv = {
-  rootDirectoryUrl: "/home/runner/work/repository-name",
-  githubToken: "xxx",
-  repositoryOwner: "jsenv",
-  repositoryName: "repository-name",
-  pullRequestNumber: 10,
-  runLink: {
-    url: "https://github.com/jsenv/repository-name/actions/runs/34",
-    text: "workflow-name#34",
-  },
-};
-```
-
-# File with dynamic names
-
-Manifest file allows to compare file with dynamic names. The content of a manifest file looks like this:
-
-```json
-{
-  "dist/file.js": "dist/file.4798774987w97er984798.js"
-}
 ```
-
-These files are generated by build tools. For example by [webpack-manifest-plugin](https://github.com/danethurber/webpack-manifest-plugin) or [rollup-plugin-output-manifest](https://github.com/shuizhongyueming/rollup-plugin-output-manifest/tree/master/packages/main).
-
-Read more in [manifestConfig](#manifestConfig) parameter
-
-# See also
-
-- [@jsenv/performance-impact](../performance-impact): Monitor pull requests impacts but on performance metrics
-- [@jsenv/lighthouse-impact](../lighthouse-impact): Monitor pull requests impacts but on lighthouse score
-
-# Note about GitHub workflow paths
-
-It would be more efficient to enable size impact workflow only if certain file changes (the one that could impact dist/ files). It could be done with `on` condition in a workflow.yml.
-
-```yml
-on:
-  pull_request:
-    paths:
-      - "index.js"
-      - "src/**"
-```
-
-But in practice humans will wonder why the workflow did not run and think something is wrong.

package/src/report_file_size_impact_in_github_pr.js

@@ -105,7 +105,7 @@ export const reportFileSizeImpactInGitHubPullRequest = async ({
       });
     },
     generatedByLink: {
-      url: "https://github.com/jsenv/core/tree/main/packages/independent/tooling/file-size-impact",
+      url: "https://github.com/jsenv/core/tree/main/packages/tooling/file-size-impact",
       text: "@jsenv/file-size-impact",
     },
     runLink,