js-dev-tool 1.2.20 → 1.2.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-dev-tool",
-  "version": "1.2.20",
+  "version": "1.2.22",
   "type": "commonjs",
   "bin": {
     "jstool": "tools.js",

package/progress/index.js

@@ -14,6 +14,7 @@ const {
   wppHandlerV4,
   isWebpackV5later,
 } = require("./progress-extras");
+const _log = console.log;
 /**
  *
  * @param {string[]} frames progress frame.
@@ -106,7 +107,7 @@ const createProgressObject = (frames, formatOpt, messageEmitter) => {
      * adjust to next line
      */
     newLine() {
-      console.log();
+      _log();
     },
     /**
      * change the fps rate
@@ -204,7 +205,7 @@ function createWebpackProgressPluginHandler(
   {
     const shortenProgress = (/** @type {number} */ pct) => {
       renderer(formatPercentage(pct));
-      pct === 1 && (console.log(), (dotted = 0));
+      pct === 1 && (_log(), (dotted = 0));
     };
     if (logFilePath !== void 0) {
       const wppLogger = lib.createLogStreamAndResolvePath(logFilePath);

package/progress/progress-extras.js

@@ -8,6 +8,7 @@
 /// <reference path="./index.d.ts"/>
 "use strict";
 const lib = require("../common");
+const _log = console.log;
 const checkENV = () => {
   const env = process.env;
   if (env.CI) return "ci";
@@ -32,7 +33,7 @@ const wppHandlerV4 = ((renderer, cwd) => {
         message +
         ` [${modules}, ${actives}] ${path}`,
     );
-    percentage === 1 && console.log();
+    percentage === 1 && _log();
   };
 })(lib.renderLine, process.cwd());
 /** @type {TWebpackProgressHandler} */
@@ -46,7 +47,7 @@ const wppHandlerV5 = ((renderer/*, cwd*/) => {
     renderer(
       `pct: ${(percentage * 100).toFixed(4)}%, process: [${message}]${pathOrPluginName ? `, info: [${pathOrPluginName}]` : ""}${args.length ? " - " : ""}${args[0]?.slice(args[0].length - maxLen) || ""}`,
     );
-    percentage === 1 && console.log();
+    percentage === 1 && _log();
   };
 })(lib.renderLine/*, process.cwd()*/);
 /** @type {boolean} */

package/tool-lib/cjbm.js

@@ -109,8 +109,9 @@ function getReplacer(ext) {
 }
 /**
  * @param {string} ext
+ * @param {NsJsTool.TDevConsole} logger
  */
-const emitProcessCallback = (ext) => {
+const emitProcessCallback = (ext, logger) => {
   /**
    * @param {string[]} sourceFiles
    */
@@ -126,7 +127,7 @@ const emitProcessCallback = (ext) => {
           fs.rename(sourceFile, afterPath, err => {
             if (err) console.error(err);
             else {
-              console.log(`renamed: ${sourceFile} => ${afterPath}`);
+              logger.log(`renamed: ${sourceFile} => ${afterPath}`);
             }
           });
         }
@@ -143,7 +144,7 @@ module.exports = () => {
     /**
      * about regex: see [[tools.js] regex - (C)onvert (J)S to (B)rowser (M)odule](https://regex101.com/r/EpuQLT/37)
      */
-    fn() {
+    fn(logger) {
       const bases = getBasePaths();
       const ext = params.ext || "js";
       /**
@@ -157,22 +158,25 @@ module.exports = () => {
           return data.replace(reImportExportDetection, getReplacer(ext));
         }, {
           bases,
-          cb: emitProcessCallback(ext)
+          cb: emitProcessCallback(ext, logger)
         },
       );
     },
     get help() {
-      return `${this.taskName}
-  ex - jstool -cmd cjbm [-root ./build | -basePath "./dist/esm,extra-tests/mini-semaphore"] [-ext js] [-test /\\.js$/] [-targets "['core.js', 'object.js']"]
-  note:
-    root     - Recursively searches for files.
-               This option is useful, but if there are directories that need to be avoided, use the 'basePath' option
-    basePath - can be "<path>,<path>,..." (array type arg)
-    ext      - specifies the module extension for import/export clauses. default is "js"
-    test     - Any file extension can be specified. (The default is /\\.js$/)
-    targets  - specify this if you want to apply it only to a specific file.
-               the file specified here should be directly under \`basePath\`!
-               value must be array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."
+      const level = 16;
+      return `jstool -cmd cjbm [-root "./build" | -basePath "./dist/esm,extra-tests/mini-semaphore"] [-ext "js"] [-test "/\\.js$/"] [-targets "['core.js', 'object.js']"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"cjbm".cyan} ${"-basePath".green} ${"dist/esm,extra-tests/mini-semaphore".gray(level)} ${"-targets".green} ${"core.js,object.js".gray(level)}
+
+${"  Options:".red}
+  ${"  root".cyan}      ${`: Recursively scan a single root directory.`.gray(level)}
+  ${"  basePath".cyan}  ${`: Source directory path(s). Use this when you want tighter scan control.`.gray(level)}
+  ${"  ext".cyan}       ${`: Module extension used in import/export clauses. default is "js".`.gray(level)}
+  ${"  test".cyan}      ${`: Target file matcher. default is /\\.js$/.`.gray(level)}
+  ${"  targets".cyan}   ${`: Limit processing to specific files directly under basePath.`.gray(level)}
+
+${"  Note:".magenta} ${`targets accepts comma-separated values or array type arg such as "['core.js','object.js']".`.gray(level)}
 `;
     },
   };

package/tool-lib/cmt-trick.js

@@ -12,10 +12,10 @@
  * @file comment trick toggle
  */
 /**
- *
  * @param {string} code
+ * @param {NsJsTool.TDevConsole} logger
  */
-function cleanup(code) {
+function cleanup(code, logger) {
   const reCleanUp = new RegExp(
     "\s*\/(?:\s*\/+\*\s+(?:ctt|comment-toggle-trick|https:\/\/coderwall)([\s\S]+?)(?:\s+)\/\*\/[\s\S]+|\s*\*\s+(?:ctt|comment-toggle-trick|https:\/\/coderwall)[\s\S]+\/\*\/([\s\S]+?))\s*\/{2,}\*\/", "g"
   );
@@ -25,12 +25,13 @@ function cleanup(code) {
 }
 /**
  * @param {string} code
+ * @param {NsJsTool.TDevConsole} logger
  */
-function doIt(code) {
+function doIt(code, logger) {
   return code.replace(
     /\/+(?=\*\s?(ctt|comment-toggle-trick|https:\/\/coderwall))/g, ($0) => {
       const slashes = $0.length === 2 ? "/" : "//";
-      console.log(
+      logger.log(
         "the-comment-toggle-trick: %s",
         /*enableBefore*/ slashes.length === 2
           ? "-->enable before<--, mute after"
@@ -47,24 +48,28 @@ function doIt(code) {
 module.exports = () => {
   return {
     taskName: "comment trick toggle",
-    fn(mode) {
+    fn(logger, mode) {
       processSources(
         /** @type {string} */ (this.taskName), (code) => {
-          return mode === "clean" ? cleanup(code) : doIt(code);
+          return mode === "clean" ? cleanup(code, logger) : doIt(code, logger);
         }, {
           ...params,
         },
       );
     },
     get help() {
-      return `Do comment trick toggle
-  It recognizes three markers: \`ctt | comment-toggle-trick | https://coderwall\`
-  jstool -cmd cmtTrick[:clean] (-base <source dir> | -bases "<source dir>,<source dir>,...") [-test re/\\\\.js$/]
-  note:
-    :clean - remove comment token etc leaving the currently enabled code
-    base (or root) - scan single source folder
-    bases          - must be array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."
-    test           - terget extension, default is /\\\\.js$/
+      const level = 16;
+      return `jstool -cmd cmtTrick[:clean] (-basePath "<source dir>" | -basePath "<source dir>,<source dir>,...") [-test "re/\\\\.js$/"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"cmtTrick:clean".cyan} ${"-basePath".green} ${"src,examples".gray(level)} ${"-test".green} ${"re/\\\\.js$/".gray(level)}
+
+${"  Options:".red}
+  ${"  :clean".cyan}     ${`: Remove comment tokens and leave the currently enabled code.`.gray(level)}
+  ${"  basePath".cyan}   ${`: Source directory path(s). Comma-separated or array type arg is accepted.`.gray(level)}
+  ${"  test".cyan}       ${`: Target file matcher. default is /\\\\.js$/.`.gray(level)}
+
+${"  Note:".magenta} ${`Recognized markers: ctt | comment-toggle-trick | https://coderwall`.gray(level)}
 `;
     },
   };

package/tool-lib/ps.js

@@ -21,8 +21,9 @@ module.exports = {
   /**
    * @param {import("fs")} fs
    * @param {import("../utils")} utils
+   * @param {NsJsTool.TDevConsole} logger
    */
-  globalize: (fs, utils) => {
+  globalize: (fs, utils, logger) => {
     /**
      * @param {string} dir
      * @param {string[]} sourceFiles
@@ -32,12 +33,12 @@ module.exports = {
     const visitDirectory = (dir, sourceFiles, testRe, recurse) => {
       if (dir.length) {
         if (!fs.existsSync(dir)) {
-          console.info(`directory: [${dir}] is not found`);
+          console.warn(`directory: [${dir}] is not found`);
         } else {
           utils.walkDirSync(dir, (dirent) => {
             const currentPath = `${dir}/${dirent.name}`;
             if (dirent.isFile() && testRe.test(dirent.name)) {
-              DEBUG && console.log("processSources::", dirent.name);
+              DEBUG && logger.log("processSources::", dirent.name);
               sourceFiles.push(currentPath);
             } else if (recurse && dirent.isDirectory()) {
               visitDirectory(currentPath, sourceFiles, testRe, true);
@@ -72,8 +73,8 @@ module.exports = {
         sourceFiles = [];
         const reFile = params.test || test;
         const actualBases = isArray(bases) ? bases : [base];
-        DEBUG && console.log("processSources::", actualBases, reFile);
-        DEBUG && console.log("processSources::re", reFile, reFile.constructor);
+        DEBUG && logger.log("processSources::", actualBases, reFile);
+        DEBUG && logger.log("processSources::re", reFile, reFile.constructor);
         if (root) {
           visitDirectory(root.trim(), sourceFiles, reFile, true);
         } else {
@@ -88,7 +89,7 @@ module.exports = {
         }
       }
       sourceFiles = sourceFiles.filter(Boolean);
-      DEBUG && console.log("processSources::processSources:", sourceFiles);
+      DEBUG && logger.log("processSources::processSources:", sourceFiles);
       let count = sourceFiles.length;
       let written = 0;
       /** @type {() => void} */

package/tool-lib/rws.js

@@ -49,18 +49,29 @@ const decrementVersion = (nversionArray) => {
  * + Too many record entries can be hard to see,  
  *   so if there are more than 10 entries, they will be truncated.
  * @param {TVersionRecords} record
+ * @param {number=} [max=5]
  */
-const shortenRecord = (record) => {
+const shortenRecord = (record, max = 5) => {
   let keys = /** @type {TVersionString[]} */ (Object.keys(record));
-  if (keys.length > 10) {
-    keys = keys.slice(keys.length - 10);
+  if (typeof max !== "number") {
+    console.warn(`rws::shortenRecord - "max" parameter is invalid, force set 5. (max: ${max})`);
+    max = 5;
+  } else {
+    if (!Number.isFinite(max)) max = 5;
+    else {
+      if (max < 1) max = 1;
+      else if (max > keys.length) max = keys.length;
+    }
+  }
+  if (keys.length > max) {
+    keys = keys.slice(keys.length - max);
     /** @type {TVersionRecords} */
-    const newRecord = {};
+    const shortRecord = {};
     for (let i = 0; i < keys.length; ) {
       const key = keys[i++];
-      newRecord[key] = record[key];
+      shortRecord[key] = record[key];
     }
-    return newRecord;
+    return shortRecord;
   }
   return record;
 };
@@ -72,7 +83,7 @@ const shortenRecord = (record) => {
 module.exports = (fs, utils) => {
   return {
     taskName: "(R)ecord(W)ebpack(S)ize",
-    fn() {
+    fn(logger) {
       const versionSourcePath = params.versionSource || "./package.json";
       /** @type {{ version: TVersionString }} */
       const thisPackage = utils.readJson(versionSourcePath);
@@ -139,7 +150,7 @@ module.exports = (fs, utils) => {
         if (prevEntry) {
           if (isDiff(prevEntry, entry)) {
             sizeRecord[versionStr] = entry;
-            utils.log(shortenRecord(sizeRecord));
+            utils.log(shortenRecord(sizeRecord, params.printMax));
             msg = "[%s] is updated";
           } else {
             needWrite = false;
@@ -163,15 +174,21 @@ module.exports = (fs, utils) => {
       }
     },
     get help() {
-      return `${this.taskName}
-  ex - jstool -cmd rws [-versionSource "<version source path>"] [-webpack lib/webpack.js -umd umd/webpack.js -dest "./dev-extras/webpack-size.json"] [-rws-tags "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"]
-  note:
-    versionSource - JSON file path used to read the "version" field. if not specified then apply "./package.json"
-    webpack  - if not specified then apply "./dist/webpack/index.js"
-    umd      - if not specified then apply "./dist/umd/index.js"
-    bin      - if not specified then apply "./dist/bin/index.js"
-    rws-tags - It is treated as parameter array separated by ":", e.g - "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"
-    dest     - if not specified then apply "./logs/webpack-size.json"
+      const level = 16;
+      return `jstool -cmd rws [-versionSource "./package.json"] [-webpack "./dist/webpack/index.js" -umd "./dist/umd/index.js" -bin "./dist/bin/index.js"]\\
+  [-dest "./logs/webpack-size.json"] [-printMax 5] [-rws-tags "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"rws".cyan} ${"-versionSource".green} ${"packages/web/package.json".gray(level)} ${"-dest".green} ${"./dev-extras/webpack-size.json".gray(level)}
+
+${"  Options:".red}
+  ${"  versionSource".cyan}  ${`: JSON file path used to read the "version" field. default is "./package.json"`.gray(level)}
+  ${"  webpack".cyan}        ${`: Source path for the webpack bundle. default is "./dist/webpack/index.js"`.gray(level)}
+  ${"  umd".cyan}            ${`: Source path for the UMD bundle. default is "./dist/umd/index.js"`.gray(level)}
+  ${"  bin".cyan}            ${`: Source path for the bin bundle. default is "./dist/bin/index.js"`.gray(level)}
+  ${"  dest".cyan}           ${`: Output path of the size record JSON. default is "./logs/webpack-size.json"`.gray(level)}
+  ${"  printMax".cyan}       ${`: Max number of record entries shown in the preview log. default is 5`.gray(level)}
+  ${"  rws-tags".cyan}       ${`: Extra tag:path pairs separated by ",". e.g. "web/login:./dist/es/web/login.mjs,webpack-esm:./dist/webpack-esm/index.mjs"`.gray(level)}
 `;
     },
   };

package/tool-lib/tools.d.ts

@@ -6,6 +6,7 @@
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
 /// <reference types="literate-regex/global"/>
+/// <reference types="tin-args" preserve="true"/>
 /**
  * @date 2023-10-25
  */
@@ -19,7 +20,7 @@ declare global {
     declare type TStringReplacer = (matchs: string, ...args: any[]) => string;
     /** use `(R)ecord(W)ebpack(S)ize` */
     declare type TRwsTags = "webpack" | "umd" | "bin";
-    declare var params: ReturnType<typeof import("tin-args")<TToolArgs>>;
+    declare var params: NsTinArgs.TTinArgsReturnType<TToolArgs>;
     declare var isArray: typeof Array.isArray;
     /**
      * @date 2025/2/18 0:46:03
@@ -65,6 +66,8 @@ declare global {
         minor?: true;
         patch?: true;
         extras: string[];
+        /** rws */
+        printMax?: number;
         /** rws, backup */
         dest: string;
         /** backup */
@@ -135,7 +138,7 @@ declare global {
         cb?: (sourceFiles: string[]) => void
     }
     declare type TJSToolEntry = {
-        fn: (mode?: string) => void;
+        fn: (logger: NsJsTool.TDevConsole, mode?: string) => void;
         help: string;
         taskName: string;
     }
@@ -145,5 +148,13 @@ declare global {
     declare type TVersionString = `${number}.${number}.${number}${string}`;
     declare type TVersionRecords = Record<TVersionString, Partial<Record<TRwsTags, number>>>;
     declare type TSizeRecordEntry = TVersionRecords["0.0.0"];
+    declare namespace NsJsTool {
+      type TDevConsole = {
+        log: Console["log"];
+        warn: Console["warn"];
+        error: Console["error"];
+        info: Console["info"];
+      };
+    }
 }
-export = {};
+export {};

package/tool-lib/zip-task.js

@@ -19,7 +19,7 @@ module.exports =
   (utils) => {
     return {
       taskName: "zip",
-      fn() {
+      fn(logger) {
         const comment = params.comment;
         const paths = params.args;
         if (Array.isArray(paths)) {
@@ -29,8 +29,18 @@ module.exports =
           }
         }
       },
-      help: `jstool -cmd zip [-comment "the comment"] lib/webpack.js lib/type-ids.js
-  It is possible to create zip files with comments
-`,
+      get help() {
+        const level = 16;
+        return `jstool -cmd zip [-comment "the comment"] lib/webpack.js lib/type-ids.js
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"zip".cyan} ${"-comment".green} ${"release artifact".gray(level)} ${"lib/webpack.js lib/type-ids.js".gray(level)}
+
+${"  Options:".red}
+  ${"  comment".cyan}  ${`: ZIP comment string embedded into the output archive.`.gray(level)}
+
+${"  Note:".magenta} ${`Pass target file paths as args after the options.`.gray(level)}
+`;
+      },
     };
   };

package/tools.js

@@ -18,8 +18,25 @@ const utils = require("./utils");
 global.params = require("tin-args")();
 global.verbose = params.verb;
 global.isArray = Array.isArray;
-require("./tool-lib/ps").globalize(fs, utils);
-utils.log(params);
+/**
+ * @date 2026/06/27 15:59:10
+ * @since v1.5.23-dev
+ * @type {NsJsTool.TDevConsole}
+ */
+const devLogger = (() => {
+  const emptyLogger = /** @type {NsJsTool.TDevConsole} */({
+    log() {},
+    info() {},
+    warn() {},
+    error() {},
+  });
+  if (process.env.CI) return emptyLogger;
+  return params.verb ? console : emptyLogger;
+})();
+/** shorthand of __`console.log`__ */
+const _log = console.log;
+if (verbose) utils.log(params);
+require("./tool-lib/ps").globalize(fs, utils, devLogger);
 /**
  * how to config terser, see {@link https://github.com/terser/terser#minify-options-structure Minify options structure}
  *
@@ -78,7 +95,7 @@ const ToolFunctions = {
    */
   replace: {
     taskName: "replace",
-    fn() {
+    fn(logger) {
       const re = params.regex;
       const after = params.after || "";
       let targets = params.args || params.targets
@@ -91,26 +108,27 @@ const ToolFunctions = {
       }
     },
     get help() {
+      const level = 16;
       return `jstool -cmd replace [-after <replacement>] -regex \"/^\\s+<!--[\\s\\S]+?-->(?:\\r?\\n)?/gm\" [-targets "<path>,<path>,..." | <args: file, file file...>]
 
 ${"  Options:".red}
-  ${"  after".cyan}  ${`: If omitted, "" (empty string) is used, meaning that the matched string is deleted.`.gray(16)}
-  ${"  targets".cyan}${`: Single path string or Array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."`.gray(16)}
+  ${"  after".cyan}  ${`: If omitted, "" (empty string) is used, meaning that the matched string is deleted.`.gray(level)}
+  ${"  targets".cyan}${`: Single path string or Array type arg, "['<path>', '<path>',...]" or "<path>,<path>,..."`.gray(level)}
 
-${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${`
+${"  remarks".magenta}${": targets - can use args parameter instead".gray(level)}${`
     It is better to use the <args: file, file file...>
-    e.g - ${"jstool".yellow} ${"-cmd".green} ${"replace".cyan} ${"-after".green} ${`".."`.red} ${"-regex".green} ${String.raw`'re/(?<=reference path=")(\.)(?=\/index.d.ts")/'`.magenta} ${"build/**/*.js".gray(16)}
+    e.g - ${"jstool".yellow} ${"-cmd".green} ${"replace".cyan} ${"-after".green} ${`".."`.red} ${"-regex".green}=${String.raw`'r/(?<=reference path=")(\.)(?=\/index.d.ts")/'`.magenta} ${"build/**/*.js".gray(level)}
                                                                                                   ^^^^^^^^^^^^^
-`.gray(16)}`;
+`.gray(level)}`;
     },
   },
   version: {
     taskName: "version",
-    fn() {
+    fn(logger) {
       let { major, minor /*, patch*/, pkgJsons = ["./package.json"] } = params;
       /** @type {string} */
       let currentVersion;
-      /** @type {string} */
+      /** @type {string=} */
       let nextVersion;
       !isArray(pkgJsons) && (pkgJsons = [pkgJsons]);
       utils.fireReplace(
@@ -156,18 +174,28 @@ ${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${
           paths,
         );
       }
-      // @ts-ignore
       console.log("version updated: %s", nextVersion);
     },
-    help: `jstool -cmd version [-major | -minor] [-pkgJsons "./package.json,../package.json"] [-extras "test/web/index.html"]
-  bump top level package.json version(can specify "package.json" paths by \`pkgJsons\` option if need), specify patch version is unnecessary.
-  note:
-    extras - can be "<path>,<path>,..." (array type arg)
-`,
+    get help() {
+      const level = 16;
+      return `jstool -cmd version [-major | -minor] [-pkgJsons "./package.json,../package.json"] [-extras "test/web/index.html"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"version".cyan} ${"-minor".green} ${"-extras".green} ${"README.md,test/web/index.html".gray(level)}
+
+${"  Options:".red}
+  ${"  major".cyan}     ${`: Bump major version and reset minor/patch to 0.`.gray(level)}
+  ${"  minor".cyan}     ${`: Bump minor version and reset patch to 0.`.gray(level)}
+  ${"  pkgJsons".cyan}  ${`: Target package.json path(s). Comma-separated or array type arg is accepted.`.gray(level)}
+  ${"  extras".cyan}    ${`: Additional files whose version strings should be replaced too.`.gray(level)}
+
+${"  Note:".magenta} ${`If neither -major nor -minor is specified, patch version is bumped.`.gray(level)}
+`;
+    },
   },
   minify: {
     taskName: "minify",
-    fn() {
+    fn(logger) {
       const Terser = require("terser");
       const sx = params.suffix;
       let suffix = ".mini";
@@ -195,12 +223,19 @@ ${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${
         opt,
       );
     },
-    help: `jstool -cmd minify -basePath extra-tests/web/mini-semaphore [-test "re/\\.js$/"] [-suffix ".mini"]
-  note:
-    basePath - can be "<path>,<path>,..." (array type arg)
-    test     - can be omit, default is \`/\\.js$/\`
-    suffix   - can be omit, default is ".mini"
-`,
+    get help() {
+      const level = 16;
+      return `jstool -cmd minify -basePath "extra-tests/web/mini-semaphore" [-test "re/\\.js$/"] [-suffix ".mini"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"minify".cyan} ${"-basePath".green} ${"dist/esm,dist/cjs".gray(level)} ${"-suffix".green} ${".min".gray(level)}
+
+${"  Options:".red}
+  ${"  basePath".cyan}  ${`: Source directory path(s). Comma-separated or array type arg is accepted.`.gray(level)}
+  ${"  test".cyan}      ${`: Target file matcher. default is /\\.js$/.`.gray(level)}
+  ${"  suffix".cyan}    ${`: Output suffix inserted before ".js". default is ".mini".`.gray(level)}
+`;
+    },
   },
   /**
    * NOTE: keep comment that start with "/&#42;" when "&#42;/" end mark appears in same line.
@@ -209,12 +244,12 @@ ${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${
    */
   rmc: {
     taskName: "rm-cstyle-cmts",
-    fn() {
+    fn(logger) {
       rmc.reset();
       if (params.rmc4ts) {
         const keepBangLine = params.rmc4ts === "keepBangLine";
         const reMultiLineChcker = /^\/\*(\*|!)\s|^\/\*(?!-).+\*\/$/;
-        const reSingleLineChecer = /^\/\/+!/;
+        const reSingleLineChecer = /^(?:\/\/+!)/;
         rmc.setListener(({ event, fragment }) => {
           if (event === /*EScannerEvent.MultiLineComment*/ 1) {
             return reMultiLineChcker.test(fragment);
@@ -240,16 +275,23 @@ ${"  remarks".magenta}${": targets - can use args parameter instead".gray(16)}${
         },
       );
     },
-    help: `$ jstool -cmd rmc [-rmc4ts[:keepBangLine]] -basePath "./dist/cjs,./dist/cjs/gulp" -test "/\\.(js|d\\.ts)$/"
-  note: basePath - can be "<path>,<path>,..." (array type arg)
-    test  - can be omit, defulat \`/\.js$/\`
-    rmc4ts- for typescript source.
-      keep comment that start with "/*" when "*/" end mark appears in same line.
-      if start with "/*-" remove it
-      keep leading "/// <reference ...>" directives above a top-level "use strict" line in CJS emit.(2026/02/03)
-    rmc4ts=keepBangLine (2025/12/24)
-          - In addition to the "rmc4ts" processing, it also preserves line comments that start with "//!".
-`,
+    get help() {
+      const level = 16;
+      return `jstool -cmd rmc [-rmc4ts[:keepBangLine]] -basePath "./dist/cjs,./dist/cjs/gulp" [-test "/\\.(js|d\\.ts)$/"] [-suffix ".clean"]
+
+${"  Example:".red}
+  ${"jstool".yellow} ${"-cmd".green} ${"rmc".cyan} ${"-rmc4ts:keepBangLine".green} ${"-basePath".green} ${"dist/cjs,dist/cjs/gulp".gray(level)} ${"-test".green} ${"/\\.(js|d\\.ts)$/".gray(level)}
+
+${"  Options:".red}
+  ${"  basePath".cyan}  ${`: Source directory path(s). Comma-separated or array type arg is accepted.`.gray(level)}
+  ${"  test".cyan}      ${`: Target file matcher. default is /\\.js$/.`.gray(level)}
+  ${"  suffix".cyan}    ${`: Output suffix inserted before ".js" when needed.`.gray(level)}
+  ${"  rmc4ts".cyan}    ${`: TypeScript-oriented mode. Preserves single-line /* */ comments except ones that start with "/*-".`.gray(level)}
+
+${"  Extra:".magenta} ${`rmc4ts:keepBangLine also preserves line comments that start with "//!".`.gray(level)}
+${"  Extra:".magenta} ${`Leading /// <reference ...> directives are kept above a top-level "use strict" line in CJS output.`.gray(level)}
+`;
+    },
   },
   zip: require("./tool-lib/zip-task")(utils),
 };
@@ -298,25 +340,25 @@ function isJSToolEntry(entry) {
  */
 function printHelp(cmd) {
   const entry = ToolFunctions[cmd];
-  console.log(`${cmd.yellow + " help:".green} ${entry.help.gray(8)}`);
+  _log(`${cmd.yellow + " help:".green} ${entry.help.gray(8)}`);
 }
 if (params.cmd) {
   const [task, mode] = params.cmd.split(":");
   const entry = ToolFunctions[task];
-  isJSToolEntry(entry) && entry.fn(mode);
+  isJSToolEntry(entry) && entry.fn(devLogger, mode);
 } else if (params.shell) {
   const SCRIPT_DIR = path.dirname(process.argv[1]);
   const arg = `${params.major ? "-major" : params.minor ? "-minor" : ""}`;
   utils.execWithOutputResult(
     `bash ${SCRIPT_DIR}/scripts/tool.sh ${params.shell} ${arg}`,
     (result) => {
-      console.log(result);
+      _log(result);
     },
     process.cwd(),
   );
 } else if (params.v) {
   const thisVersion = require("./package.json").version;
-  console.log(
+  _log(
     `${"jstool".magenta} in "js-dev-scripts", version: ${thisVersion.green}
 more details see ${"https://github.com/jeffy-g/js-dev-scripts".blue}`,
   );
@@ -327,7 +369,7 @@ more details see ${"https://github.com/jeffy-g/js-dev-scripts".blue}`,
       printHelp(cmdName);
     } else {
       const commands = Object.keys(ToolFunctions);
-      console.log(`
+      _log(`
 Usage: node jstool -cmd <command name>
     - - - - available commands:`);
       for (const cmd of commands) {

package/utils.d.ts

@@ -165,11 +165,11 @@ export function copyText(content: string, message?: string, chcp65001?: boolean)
  * @param regex
  * @param replacement
  * @param paths Paths that do not exist are ignored
- * @param [async]
+ * @param [opt]
  *
  * @date 2019-4-26
  */
-export function fireReplace(regex: RegExp, replacement: string | Function, paths: string[], async?: boolean): void;
+export function fireReplace(regex: RegExp, replacement: string | Function, paths: string[], opt?: { async?: boolean; verbose?: boolean }): void;
 export const CI: boolean;
 /**
  * Nothing is logged in a CI environment.

package/utils.js

@@ -27,6 +27,7 @@ const lib = require("./common");
 const tinArgs = require("tin-args");
 const { listDependenciesOf } = require("./extras/list-deps-of");
 const CI = !!process.env.CI;
+const _log = console.log;
 /**
  * Nothing is logged in a CI environment.
  */
@@ -53,7 +54,6 @@ function extractVersion(versionString = process.version) {
   const [major = 0, minor = 0, patch = 0] = pv ? pv.map((value, i) => {
     return (i > 0 && +value) || void 0;
   }).slice(1) : [];
-  console.log("result:", major, minor, patch);
   return { major, minor, patch };
 }
 /**
@@ -208,13 +208,14 @@ let nodeReplace;
  * @param {RegExp} regex
  * @param {string | Function} replacement
  * @param {string[]} paths Paths that do not exist are ignored
- * @param {boolean} [async]
+ * @param {{ async?: boolean; verbose?: boolean }} [opt]
  *
  * @date 2019-4-26
  */
-function fireReplace(regex, replacement, paths, async = false) {
+function fireReplace(regex, replacement, paths, opt) {
   // @ts-ignore "replace" is peerDependencies
   nodeReplace === void 0 && (nodeReplace = require("replace"));
+  opt = { async: false, verbose: false, ...opt };
   if (Array.isArray(paths)) {
     paths = paths.filter((path) => fs.existsSync(path));
     nodeReplace({
@@ -222,9 +223,9 @@ function fireReplace(regex, replacement, paths, async = false) {
       replacement,
       paths,
       recursive: false,
-      silent: false,
+      silent: !opt.verbose,
       preview: false,
-      async,
+      async: opt.async,
       ignoreCase: false,
       multiline: false,
     });
@@ -257,16 +258,16 @@ function compressScript(scriptPath, comment = "") {
     compressionMethod: zlibZip.CompressionMethod.DEFLATE,
     os: zlibZip.OperatingSystem.MSDOS,
   });
-  console.log(`added ${scriptPath} to zip`);
-  console.log("start compress...");
+  _log(`added ${scriptPath} to zip`);
+  _log("start compress...");
   console.time("zip:compress");
   const compressed = zip.compress();
   console.timeEnd("zip:compress");
-  console.log("compress done.\n");
+  _log("compress done.\n");
   const pp = path.parse(scriptPath);
   const output = `${pp.dir ? pp.dir + "/" : ""}${pp.name}.zip`;
   fs.writeFile(output, compressed, (err) => {
-    console.log(`\nzip file created, error: ${err}\n => ${output}`);
+    _log(`\nzip file created, error: ${err}\n => ${output}`);
   });
 }
 /**
@@ -283,16 +284,16 @@ function compressScript2(scriptPath, comment = "") {
   const pp = path.parse(scriptPath);
   const output = fs.createWriteStream(`${pp.dir}/${pp.name}.zip`);
   output.on("close", function () {
-    console.log(archive.pointer() + " total bytes");
-    console.log(
+    _log(archive.pointer() + " total bytes");
+    _log(
       "archiver has been finalized and the output file descriptor has closed.",
     );
   });
   output.on("end", function () {
-    console.log("Data has been drained");
+    _log("Data has been drained");
   });
   archive.on("progress", (progress) => {
-    console.log(progress.entries.processed);
+    _log(progress.entries.processed);
   });
   archive.pipe(output);
   archive.file(scriptPath, {
@@ -313,7 +314,7 @@ function compressScript2(scriptPath, comment = "") {
  * @param {(result: string) => void} doneCallbackWithArgs gulp callback function.
  */
 function execWithOutputResult(command, doneCallbackWithArgs, cwd) {
-  console.log();
+  _log();
   const { exec } = require("child_process");
   return exec(command, { cwd }, (err, stdout /* , stderr */) => {
     if (err) {
@@ -423,7 +424,7 @@ function copyText(content, message = "text copied!", chcp65001 = true) {
       if (err) {
         console.error(err);
       } else {
-        console.log(message, stdout);
+        _log(message, stdout);
       }
     });
     // @ts-ignore