Adapt comments to align with other package managers

packages/safe-chain/src/packagemanager/pip/createPackageManager.js

@@ -9,10 +9,12 @@ import {
 
 /**
  * @param {string} [command]
+ * @returns {import("../currentPackageManager.js").PackageManager}
  */
 export function createPipPackageManager(command = "pip") {
   /**
    * @param {string[]} args
+   * @returns {boolean}
    */
   function isSupportedCommand(args) {
     const scanner = findDependencyScannerForCommand(
@@ -24,6 +26,7 @@ export function createPipPackageManager(command = "pip") {
 
   /**
    * @param {string[]} args
+   * @returns {ReturnType<import("../currentPackageManager.js").PackageManager["getDependencyUpdatesForCommand"]>}
    */
   function getDependencyUpdatesForCommand(args) {
     const scanner = findDependencyScannerForCommand(
@@ -40,6 +43,9 @@ export function createPipPackageManager(command = "pip") {
   };
 }
 
+/**
+ * @type {Record<string, import("./dependencyScanner/commandArgumentScanner.js").CommandArgumentScanner>}
+ */
 const commandScannerMapping = {
   [pipInstallCommand]: commandArgumentScanner(),
   [pipDownloadCommand]: commandArgumentScanner(), // download also fetches packages from PyPI
@@ -47,21 +53,27 @@ const commandScannerMapping = {
   // Other commands return null scanner by default
 };
 
-const NULL_SCANNER = {
-  shouldScan: () => false,
-  scan: () => [],
-};
+/**
+ * @returns {import("./dependencyScanner/commandArgumentScanner.js").CommandArgumentScanner}
+ */
+function nullScanner() {
+  return {
+    shouldScan: () => false,
+    scan: () => [],
+  };
+}
 
 /**
- * @param {Record<string, any>} scanners
+ * @param {Record<string, import("./dependencyScanner/commandArgumentScanner.js").CommandArgumentScanner>} scanners
  * @param {string[]} args
+ * @returns {import("./dependencyScanner/commandArgumentScanner.js").CommandArgumentScanner}
  */
 function findDependencyScannerForCommand(scanners, args) {
   const command = getPipCommandForArgs(args);
   if (!command) {
-    return NULL_SCANNER;
+    return nullScanner();
   }
 
   const scanner = scanners[command];
-  return scanner || NULL_SCANNER;
+  return scanner || nullScanner();
 }

packages/safe-chain/src/packagemanager/pip/dependencyScanner/commandArgumentScanner.js

@@ -1,9 +1,31 @@
 import { parsePackagesFromInstallArgs } from "../parsing/parsePackagesFromInstallArgs.js";
 import { hasDryRunArg } from "../utils/pipCommands.js";
 
+/**
+ * @typedef {Object} ScanResult
+ * @property {string} name
+ * @property {string} version
+ * @property {string} type
+ */
+
+/**
+ * @typedef {Object} ScannerOptions
+ * @property {boolean} [ignoreDryRun]
+ */
+
+/**
+ * @typedef {Object} CommandArgumentScanner
+ * @property {(args: string[]) => Promise<ScanResult[]> | ScanResult[]} scan
+ * @property {(args: string[]) => boolean} shouldScan
+ */
+
 /**
  * @param {{ ignoreDryRun?: boolean }} [options]
  */
+/**
+ * @param {ScannerOptions} [options]
+ * @returns {CommandArgumentScanner}
+ */
 export function commandArgumentScanner(options = {}) {
   const { ignoreDryRun = false } = options;
 
@@ -17,6 +39,10 @@ export function commandArgumentScanner(options = {}) {
   /**
    * @param {string[]} args
    */
+  /**
+   * @param {string[]} args
+   * @returns {Promise<ScanResult[]> | ScanResult[]}
+   */
   function scan(args) {
     return scanDependencies(args);
   }
@@ -38,6 +64,10 @@ function shouldScanDependencies(args, ignoreDryRun) {
 /**
  * @param {string[]} args
  */
+/**
+ * @param {string[]} args
+ * @returns {Promise<ScanResult[]> | ScanResult[]}
+ */
 function scanDependencies(args) {
   return checkChangesFromArgs(args);
 }
@@ -45,6 +75,10 @@ function scanDependencies(args) {
 /**
  * @param {string[]} args
  */
+/**
+ * @param {string[]} args
+ * @returns {Promise<ScanResult[]> | ScanResult[]}
+ */
 export function checkChangesFromArgs(args) {
   const packageUpdates = parsePackagesFromInstallArgs(args);