mega-linter-runner 9.4.0 → 9.5.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,109 @@ 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: "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: "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;
@@ -79,6 +89,11 @@ export class MegaLinterRunner {
     }
 
     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 +101,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 =
@@ -219,7 +236,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-linter-runner",
-  "version": "9.4.0",
+  "version": "9.5.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",
+    "uuid": "^14.0.0",
     "which": "^6.0.0",
-    "yeoman-environment": "^5.0.0",
-    "yeoman-generator": "^7.1.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",
+    "diff": "^9.0.0",
+    "ip-address": "^10.1.1",
+    "serialize-javascript": "^7.0.5",
+    "semver": "7.8.0",
     "tmp": "0.2.5"
   }
 }