mega-linter-runner 9.4.0 → 9.6.0

package/lib/options.js

@@ -14,11 +14,42 @@ import { DEFAULT_RELEASE } from "./config.js";
 // Initialization and Public Interface
 //------------------------------------------------------------------------------
 
+export const KNOWN_FLAVORS = [
+  "all",
+  "c_cpp",
+  "ci_light",
+  "cupcake",
+  "documentation",
+  "dotnet",
+  "dotnetweb",
+  "formatters",
+  "go",
+  "java",
+  "javascript",
+  "php",
+  "python",
+  "ruby",
+  "rust",
+  "salesforce",
+  "security",
+  "swift",
+  "terraform",
+];
+
+export const KNOWN_CONTAINER_ENGINES = ["docker", "podman"];
+
+export const KNOWN_PLATFORMS = ["linux/amd64", "linux/arm64"];
+
 // exports "parse(args)", "generateHelp()", and "generateHelpForOption(optionName)"
 export const optionsDefinition = optionator.default({
-  prepend: "mega-linter [options]",
+  prepend: "mega-linter [options] [FILES...]",
+  append:
+    "Tips:\n" +
+    "  - Pass MegaLinter env variables with -e KEY=VALUE (repeat or use commas: -e KEY1=val1,KEY2=val2).\n" +
+    "  - List all 2300+ MegaLinter env variables with `mega-linter-runner --list-vars [pattern]`.\n" +
+    "  - Online reference: https://megalinter.io/latest/config-variables/",
   defaults: {
-    concatRepeatedArrays: true,
+    concatRepeatedArrays: [true, { oneValuePerFlag: true }],
     mergeRepeatedObjects: true,
   },
   options: [
@@ -27,22 +58,26 @@ export const optionsDefinition = optionator.default({
       alias: "r",
       type: "String",
       default: DEFAULT_RELEASE,
-      description: "MegaLinter version",
-      example: ["stable", "latest", `${DEFAULT_RELEASE}.1.2`],
+      description:
+        "MegaLinter version tag pulled from ghcr.io/oxsecurity/megalinter. Accepts a release tag (`v9.1.2`), a moving tag (`stable`, `latest`, `beta`, `alpha`), or a major-version tag (`v9`).",
+      example: ["stable", "latest", "beta", `${DEFAULT_RELEASE}.1.2`],
     },
     {
       option: "flavor",
       alias: "f",
       type: "String",
       default: "all",
-      description: "MegaLinter flavor",
-      example: ["dotnet", "javascript", "java", "php", "python"],
+      description:
+        "Specialized MegaLinter image to pull. Smaller flavors start faster and avoid pulling tools you do not need.\n" +
+        `Allowed values: ${KNOWN_FLAVORS.join(", ")}.`,
+      example: KNOWN_FLAVORS,
     },
     {
       option: "image",
       alias: "d",
       type: "String",
-      description: "MegaLinter docker image",
+      description:
+        "Full docker image reference to run instead of resolving from --flavor/--release. Mutually exclusive with --flavor.",
       example: [
         "ghcr.io/oxsecurity/megalinter:latest",
         `ghcr.io/oxsecurity/megalinter:${DEFAULT_RELEASE}`,
@@ -55,40 +90,47 @@ export const optionsDefinition = optionator.default({
       type: "path::String",
       default: ".",
       description:
-        "Directory containing the files to lint (default: current directory)",
-      example: ["./path/to/my/files"],
+        "Directory containing the files to lint (default: current working directory). Mounted into the container at /tmp/lint.",
+      example: ["./path/to/my/files", "/abs/path/to/repo"],
     },
     {
       option: "env",
       alias: "e",
       type: "[String]",
-      description: "Environment variable (multiple)",
+      description:
+        "MegaLinter environment variable in KEY=VALUE form. Repeat the flag for multiple variables, or pass several with a single flag using commas (KEY1=val1,KEY2=val2). Commas inside a single value (e.g. ENABLE_LINTERS=A,B) are preserved as-is, quoted or not. Run `mega-linter-runner --list-vars [pattern]` to discover supported variables.",
       example: [
-        "-e 'ENABLE=JAVASCRIPT' -e 'SHOW_ELAPSED_TIME=true'",
-        "-e 'ENABLE=JAVASCRIPT,YAML' -e 'DISABLE_LINTERS=MARKDOWN_MARKDOWN_LINK_CHECK'",
+        "-e ENABLE=JAVASCRIPT -e SHOW_ELAPSED_TIME=true",
+        "-e ENABLE_LINTERS=YAML_PRETTIER,YAML_YAMLLINT",
+        "-e APPLY_FIXES=all,LOG_LEVEL=DEBUG",
+        "--env=DISABLE_LINTERS=MARKDOWN_MARKDOWN_LINK_CHECK",
       ],
     },
     {
       option: "fix",
       type: "Boolean",
-      description: "Apply formatters and fixes in linted sources",
+      description:
+        "Apply formatters and auto-fixes (equivalent to -e APPLY_FIXES=all).",
     },
     {
       option: "filesonly",
       type: "Boolean",
-      description: "Do not run linters with project as CLI lint mode",
+      description:
+        "Do not run linters in `project` CLI lint mode (equivalent to -e SKIP_CLI_LINT_MODES=project).",
     },
     {
       option: "json",
       alias: "j",
       type: "Boolean",
-      description: "Outputs results as JSON string",
+      description:
+        "Output the run summary as a JSON object on stdout (equivalent to -e JSON_REPORTER=true).",
     },
     {
       option: "nodockerpull",
       alias: "n",
       type: "Boolean",
-      description: "Do not pull docker image before running it",
+      description:
+        "Skip `docker pull` before running. Useful for offline / cached / locally built images.",
     },
     {
       option: "platform",
@@ -96,86 +138,127 @@ export const optionsDefinition = optionator.default({
       type: "String",
       default: "linux/amd64",
       description:
-        "Force a docker image platform (currently, only linux/amd64 works)",
+        "Container image platform forwarded to `docker --platform`.\n" +
+        `Allowed values: ${KNOWN_PLATFORMS.join(", ")} (linux/arm64 support is partial — see docs).`,
+      example: KNOWN_PLATFORMS,
     },
     {
       option: "debug",
       type: "Boolean",
-      description: "See debug logs",
+      description:
+        "Enable verbose logs (equivalent to -e LOG_LEVEL=DEBUG).",
     },
     {
       option: "help",
       alias: "h",
       type: "Boolean",
       description:
-        "Show help (mega-linter --help OPTIONNAME to see option detail)",
+        "Show help. Pass an option name as positional arg to see details: `mega-linter-runner --help env`.",
     },
     {
       option: "version",
       alias: "v",
       type: "Boolean",
-      description: "Show version",
+      description: "Print the mega-linter-runner version and exit.",
     },
     {
       option: "install",
       alias: "i",
       type: "Boolean",
-      description: "Generate MegaLinter configuration in your project",
+      description:
+        "Interactive generator that scaffolds .mega-linter.yml and CI workflow files in the current project.",
     },
     {
       option: "custom-flavor-setup",
       alias: "cfs",
       type: "Boolean",
-      description: "Generate files to create a custom flavor",
+      description: "Generate scaffolding files to build a custom MegaLinter flavor.",
     },
     {
       option: "custom-flavor-linters",
       type: "String",
-      description: "comma-separated list of linters to include in custom flavor",
+      description:
+        "Comma-separated list of MegaLinter linter keys to include in the custom flavor (e.g. YAML_PRETTIER,YAML_YAMLLINT).",
+      example: ["YAML_PRETTIER,YAML_YAMLLINT", "PYTHON_RUFF,PYTHON_BLACK"],
     },
     {
       option: "upgrade",
       alias: "u",
       type: "Boolean",
-      description: "Upgrade local repository MegaLinter configuration",
+      description:
+        "Upgrade the local MegaLinter configuration (.mega-linter.yml and related CI files) to the current major version.",
+    },
+    {
+      option: "prompt",
+      type: "Boolean",
+      description:
+        "Enable interactive prompts. Use --no-prompt to run non-interactively. For `--upgrade`, that proceeds with the upgrade and skips optional follow-up prompts.",
     },
     {
       option: "container-name",
       alias: "containername",
       type: "String",
-      description: "Specify MegaLinter container name",
+      description:
+        "Override the container name passed to `docker run --name`.",
+      example: ["my-megalinter-run"],
     },
     {
       option: "container-engine",
       alias: "",
       type: "String",
       default: "docker",
-      description: "Use docker or podman as container engine",
-    },    
+      description:
+        "Container engine binary to invoke.\n" +
+        `Allowed values: ${KNOWN_CONTAINER_ENGINES.join(", ")}.`,
+      example: KNOWN_CONTAINER_ENGINES,
+    },
     {
       option: "remove-container",
       type: "Boolean",
-      description: "Remove MegaLinter Docker container when done (default: true since v7.8.0)",
+      description:
+        "Remove the MegaLinter container when done. This is the default since v7.8.0; use --no-remove-container to keep it.",
     },
     {
       option: "no-remove-container",
       type: "Boolean",
-      description: "Do not remove MegaLinter Docker container when done",
+      description:
+        "Keep the MegaLinter container after the run. Useful for `docker logs <container>` post-mortem.",
+    },
+    {
+      option: "user-map",
+      type: "Boolean",
+      description:
+        "Run the container as a non-root user. On POSIX systems this uses your user. On other hosts it uses 1000:1000.",
+    },
+    {
+      option: "no-user-map",
+      type: "Boolean",
+      description:
+        "Run the container as root.",
     },
     {
       option: "codetotal",
       type: "Boolean",
-      description: "Run CodeTotal locally",
+      description:
+        "[NOT ACTIVELY MAINTAINED] Launch CodeTotal locally (companion UI for MegaLinter results). The CodeTotal project is no longer actively maintained; use at your own risk.",
     },
     {
       option: "codetotal-url",
       type: "String",
       default: "http://localhost:8081/",
-      description: "URL Hosting CodeTotal once launched",
+      description:
+        "[NOT ACTIVELY MAINTAINED] URL where the local CodeTotal instance will be served. The CodeTotal project is no longer actively maintained.",
+      example: ["http://localhost:8081/"],
+    },
+    {
+      option: "list-vars",
+      type: "Boolean",
+      description:
+        "List MegaLinter environment variables that can be passed via -e. Add a positional substring to filter (case-insensitive), e.g. `mega-linter-runner --list-vars PYTHON_RUFF`. Add --json for machine-readable output.",
     },
   ],
   mutuallyExclusive: [
-    ["help", "version", "install"],
+    ["help", "version", "install", "list-vars"],
     ["image", "flavor"],
   ],
 });

package/lib/runner.js

@@ -1,4 +1,6 @@
-import { optionsDefinition } from "./options.js"
+import { optionsDefinition, KNOWN_CONTAINER_ENGINES } from "./options.js"
+import { expandEnvEntries } from "./env-parser.js";
+import { listVars } from "./list-vars.js";
 import { spawnSync } from "child_process";
 import { default as c } from 'chalk';
 import * as path from 'path';
@@ -28,6 +30,14 @@ export class MegaLinterRunner {
       return { status: 0, stdout: outputString };
     }
 
+    // List MegaLinter env variables (optionally filtered)
+    if (options.listVars) {
+      const pattern = options._ && options._.length ? options._[0] : null;
+      const { stdout } = listVars({ pattern, asJson: options.json === true });
+      console.log(stdout);
+      return { status: 0, stdout };
+    }
+
     // Show version
     if (options.version) {
       let v = process.env.npm_package_version;
@@ -73,12 +83,19 @@ export class MegaLinterRunner {
 
     // Run upgrader from v4 to v5
     if (options.upgrade) {
-      const megaLinterUpgrader = new MegaLinterUpgrader();
+      const megaLinterUpgrader = new MegaLinterUpgrader({
+        noPrompt: options.prompt === false,
+      });
       await megaLinterUpgrader.run();
       return { status: 0 };
     }
 
     if (options.codetotal) {
+      console.warn(
+        c.yellow(
+          "[WARNING] CodeTotal is not actively maintained. The --codetotal integration is kept for legacy users and may be removed in a future major release.",
+        ),
+      );
       const codeTotalRunner = new CodeTotalRunner(options);
       await codeTotalRunner.run();
       return { status: 0 }
@@ -86,8 +103,10 @@ export class MegaLinterRunner {
 
     // Build MegaLinter docker image name with flavor and release version
     this.containerEngine = options.containerEngine || "docker";
-    if (this.containerEngine !== "docker" && this.containerEngine !== "podman") {
-      throw new Error(`Invalid container engine: ${this.containerEngine}. Supported engines are 'docker' and 'podman'.`);
+    if (!KNOWN_CONTAINER_ENGINES.includes(this.containerEngine)) {
+      throw new Error(
+        `Invalid container engine: ${this.containerEngine}. Supported engines are ${KNOWN_CONTAINER_ENGINES.join(", ")}.`,
+      );
     }
     const release = options.release in ["stable"] ? DEFAULT_RELEASE : options.release;
     const dockerImageName =
@@ -199,8 +218,16 @@ export class MegaLinterRunner {
     if (options["containerName"]) {
       commandArgs.push(...["--name", options["containerName"]]);
     }
-    commandArgs.push(...["-v", "/var/run/docker.sock:/var/run/docker.sock:rw"]);
     commandArgs.push(...["-v", `${lintPath}:/tmp/lint:rw`]);
+    if (options["userMap"] === true) {
+      const runtimeUid =
+        typeof process.getuid === "function" ? process.getuid() : 1000;
+      const runtimeGid =
+        typeof process.getgid === "function" ? process.getgid() : 1000;
+      commandArgs.push(...["-e", `MEGALINTER_UID=${runtimeUid}`]);
+      commandArgs.push(...["-e", `MEGALINTER_GID=${runtimeGid}`]);
+      commandArgs.push(...["-e", "HOME=/home/megalinter"]);
+    }
     if (emptyEnvFile) {
       commandArgs.push(...["-v", `${emptyEnvFile}:/tmp/lint/.env:ro`]);
     }
@@ -219,7 +246,7 @@ export class MegaLinterRunner {
       }
     }
     if (options.env) {
-      for (const envVarEqualsValue of options.env) {
+      for (const envVarEqualsValue of expandEnvEntries(options.env)) {
         commandArgs.push(...["-e", envVarEqualsValue]);
       }
     }

package/lib/upgrade.js

@@ -8,7 +8,8 @@ import { asciiArt } from "./ascii.js";
 import { DEFAULT_RELEASE, GLOB_IGNORE_PATTERNS } from "./config.js";
 
 export class MegaLinterUpgrader {
-  constructor() {
+  constructor({ noPrompt = false } = {}) {
+    this.noPrompt = noPrompt;
     this.replacements = [
       // Documentation base URL
       {
@@ -462,10 +463,10 @@ jobs:
       },
       // Create pull request action
       {
-        regex: /peter-evans\/create-pull-request@v(3|4|5|6)/gm,
-        replacement: `peter-evans/create-pull-request@v7`,
-        test: "peter-evans/create-pull-request@v6",
-        testRes: `peter-evans/create-pull-request@v7`,
+        regex: /peter-evans\/create-pull-request@v(3|4|5|6|7)/gm,
+        replacement: `peter-evans/create-pull-request@v8`,
+        test: "peter-evans/create-pull-request@v7",
+        testRes: `peter-evans/create-pull-request@v8`,
       },
       // Auto-commit action
       {
@@ -553,15 +554,19 @@ jobs:
 
   async run() {
     console.log(asciiArt());
-    const promptsUpgradeRes = await prompts({
-      name: "upgrade",
-      message: c.blueBright(
-        `This assistant will automatically upgrade your local files so you use MegaLinter ${DEFAULT_RELEASE}\nPlease confirm to proceed :)`
-      ),
-      type: "confirm",
-      initial: true,
-    });
-    if (promptsUpgradeRes.upgrade === false) {
+    const confirmedUpgrade = this.noPrompt
+      ? true
+      : (
+        await prompts({
+          name: "upgrade",
+          message: c.blueBright(
+            `This assistant will automatically upgrade your local files so you use MegaLinter ${DEFAULT_RELEASE}\nPlease confirm to proceed :)`
+          ),
+          type: "confirm",
+          initial: true,
+        })
+      ).upgrade;
+    if (confirmedUpgrade === false) {
       console.log(
         `You should upgrade to ${DEFAULT_RELEASE} to benefit from latest versions of linters, and more features :)`
       );
@@ -580,6 +585,9 @@ jobs:
       )
     );
     console.log("");
+    if (this.noPrompt) {
+      return;
+    }
     // Propose to try ox service
     const promptsOXRes = await prompts({
       name: "ox",
@@ -662,4 +670,3 @@ jobs:
     }
   }
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-linter-runner",
-  "version": "9.4.0",
+  "version": "9.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/oxsecurity/megalinter.git"
@@ -92,10 +92,10 @@
     "optionator": "^0.9.3",
     "prompts": "^2.4.2",
     "simple-git": "^3.28.0",
-    "uuid": "^13.0.0",
-    "which": "^6.0.0",
-    "yeoman-environment": "^5.0.0",
-    "yeoman-generator": "^7.1.0"
+    "uuid": "^14.0.0",
+    "which": "^7.0.0",
+    "yeoman-environment": "^6.0.0",
+    "yeoman-generator": "^8.0.0"
   },
   "devDependencies": {
     "assert": "^2.1.0",
@@ -103,7 +103,10 @@
     "mocha": "^11.0.0"
   },
   "resolutions": {
-    "semver": "7.7.4",
-    "tmp": "0.2.5"
+    "diff": "^9.0.0",
+    "ip-address": "^10.1.1",
+    "serialize-javascript": "^7.0.5",
+    "semver": "7.8.5",
+    "tmp": "0.2.7"
   }
 }