@code-pushup/js-packages-plugin 0.34.0 → 0.39.0

package/CONTRIBUTING.md

@@ -2,9 +2,19 @@
 
 ## Adding new package managers
 
-In order to add a support for a new package manager, one needs to do the following.
+In order to add a support for a new package manager, one needs to do the following:
 
-1. Expand `packageManagerSchema` in `config.ts`.
-2. Expand `<command>Args` in `runner/<command>/constants.ts` with a set of arguments to be run for a given package manager command.
-3. Create a custom type in `runner/<command>/types.ts` with relevant properties based on expected command JSON output.
-4. Create a function in `runner/<command>/unify-type.ts` that will transform JSON output into a normalized type `OutdatedResult` or `AuditResult` and add it to `normalized<command>Mapper` in `runner/<command>/constants.ts`.
+1. Expand `packageManagerIdSchema` in `config.ts`.
+2. Create a new object of `PackageManager` type in `package-managers/<name>/<name>.ts` and fill it in with all relevant data. Following the current pattern of separate files for audit and outdated result and types is recommended.
+3. Extend `package-managers/package-managers.ts` record with the new package manager.
+
+> [!NOTE]
+> Should your package manager require specific behaviour, feel free to request a property addition or change.
+
+### Notable properties
+
+- `(audit|check).unifyResult()`: In order to process the results in a unified way, the expected type needs to be defined in `runner/(audit|check)/types.ts` and its transformation to normalised result implemented in `runner/(audit|check)/unify-type.ts`. This function is then referenced in the object to be called accordingly.
+- `audit.getCommandArgs(depGroup)`: The `audit` command is run for one dependency group. In order to filter out the other dependencies, the arguments are provided dynamically based on this function. One may include frequently used arguments from `COMMON_AUDIT_ARGS`.
+- `audit.ignoreExitCode`: Some package managers do not allow non-zero exit code override. To ignore non-zero exit code, set this property to `true`.
+- `audit.supportedDepGroups`: Some package managers do not support `audit` check for all types of dependencies (e.g. optional). In that case, please list a supported subset of dependencies in this property. By default, all dependency groups are considered supported.
+- `audit.postProcessResult()`: The `audit` check often does not offer exclusive result for all dependency groups. In order to filter out duplicates after the results are normalised, add a post-processing function here.

package/README.md

@@ -22,7 +22,21 @@ It supports the following package managers:
 
 1. If you haven't already, install [@code-pushup/cli](../cli/README.md) and create a configuration file.
 
-2. Insert plugin configuration with your package manager. By default, both `audit` and `outdated` checks will be run. The result should look as follows:
+2. Install as a dev dependency with your package manager:
+
+   ```sh
+   npm install --save-dev @code-pushup/js-packages-plugin
+   ```
+
+   ```sh
+   yarn add --dev @code-pushup/js-packages-plugin
+   ```
+
+   ```sh
+   pnpm add --save-dev @code-pushup/js-packages-plugin
+   ```
+
+3. Insert plugin configuration with your package manager. By default, both `audit` and `outdated` checks will be run. The result should look as follows:
 
    ```js
    import jsPackagesPlugin from '@code-pushup/js-packages-plugin';
@@ -50,7 +64,7 @@ It supports the following package managers:
    };
    ```
 
-3. (Optional) Reference individual audits or the provided plugin groups which you wish to include in custom categories (use `npx code-pushup print-config` to list audits and groups).
+4. (Optional) Reference individual audits or the provided plugin groups which you wish to include in custom categories (use `npx code-pushup print-config` to list audits and groups).
 
    💡 Assign weights based on what influence each command should have on the overall category score (assign weight 0 to only include as extra info, without influencing category score).
 
@@ -88,7 +102,7 @@ It supports the following package managers:
    };
    ```
 
-4. Run the CLI with `npx code-pushup collect` and view or upload report (refer to [CLI docs](../cli/README.md)).
+5. Run the CLI with `npx code-pushup collect` and view or upload report (refer to [CLI docs](../cli/README.md)).
 
 ## Plugin architecture