Super-Linter Documentation

To integrate the tool into the Super-Linter execution flow:

1. Register the language: Add a new entry to LANGUAGES_ARRAY in lib/globals/languages.sh. Use the format "<LANGUAGE_NAME>_<TOOL_NAME>" (e.g., PYTHON_RUFF) and keep it alphabetically ordered.
2. Define the command: In lib/functions/linterCommands.sh, define LINTER_COMMANDS_ARRAY_<LANGUAGE_NAME>.
   • Example: LINTER_COMMANDS_ARRAY_GO_MODULES=(golangci-lint run --allow-parallel-runners)
3. Handle custom arguments: If users should customize arguments, define <LANGUAGE_NAME>_COMMAND_ARGS and use AddOptionsToCommand to inject them.
4. Configure Check/Fix modes: In lib/globals/linterCommandsOptions.sh, define options for the tool's specific modes:
   • If the tool is Fix-by-default: Define <LANGUAGE_NAME>_CHECK_ONLY_MODE_OPTIONS=(...).
   • If the tool is Check-only-by-default: Define <LANGUAGE_NAME>_FIX_MODE_OPTIONS=(...).
   • If it supports both, define both.

<LANGUAGE_NAME>_COMMAND_ARGS="${<LANGUAGE_NAME>_COMMAND_ARGS:-""}"
if [ -n "${<LANGUAGE_NAME>_COMMAND_ARGS:-}" ]; then
  export <LANGUAGE_NAME>_COMMAND_ARGS
  AddOptionsToCommand "LINTER_COMMANDS_ARRAY_<LANGUAGE_NAME>" "${<LANGUAGE_NAME>_COMMAND_ARGS}"
fi

To add a Java-based tool:

1. Create a directory dependencies/<name-of-tool>.
2. Create dependencies/<name-of-tool>/build.gradle with the following structure:

   repositories {
     mavenLocal()
     mavenCentral()
   }
   
   dependencies {
     implementation 'your:dependency-here:version'
   }
   
   group 'com.github.super-linter'
   version '1.0.0-SNAPSHOT'

3. Update the dependencies section in that build.gradle to include your specific dependencies.
4. Add these lines to the Dockerfile to run an installation script:

   COPY scripts/install-<name-of-tool>.sh /
   RUN --mount=type=secret,id=GITHUB_TOKEN /<name-of-tool>.sh && rm -rf /<name-of-tool>.sh

5. Implement the installation logic in scripts/install-<name-of-tool>.sh. You can extract the version from build.gradle using awk.
6. Add the tool to the java-gradle group in the Dependabot configuration.

To ensure Super-Linter identifies the correct files for your new tool, you must implement logic in lib/functions/buildFileList.sh. Depending on how the tool identifies files, choose one of the following three approaches:

1. File extension or name check

Use this if the tool targets specific extensions. Add an elif clause to the BuildFileArrays function in lib/functions/buildFileList.sh. You can use these variables:

• FILE_TYPE: the file extension.
• BASE_FILE: the name of the file.
• FILE_DIR_NAME: the directory path.

2. File contents check

Use this if you need to inspect file contents to determine if the tool should run.

1. Implement a detection function in lib/functions/detectFiles.sh.
2. Add an elif clause in the BuildFileArrays function in lib/functions/buildFileList.sh that calls your detection function.

3. Entire workspace check

Use this if the tool lints the entire workspace (e.g., via a configuration file).

1. Add logic to the BuildFileList function in lib/functions/buildFileList.sh to handle the workspace test case.
2. In BuildFileArrays, add the file to the language-specific array when "${FILE}" == "${GITHUB_WORKSPACE}".
3. Update the README to include the tool in the list of tools that check the entire workspace.

Tip: To optimize performance, combine extension checks with content checks (e.g., only run content detection on .yaml files).

# Example: Extension check
elif [ "${FILE_TYPE}" == "ext" ]; then
  echo "${FILE}" >>"${FILE_ARRAYS_DIRECTORY_PATH}/file-array-<LANGUAGE_NAME>"
fi

# Example: Content check
elif DetectCloudFormationFile "${FILE}"; then
  echo "${FILE}" >>"${FILE_ARRAYS_DIRECTORY_PATH}/file-array-CLOUDFORMATION"
fi

If your tool requires the CheckFileType fallback (using the GNU file utility) in lib/functions/buildFileList.sh, follow these steps:

1. Create a helper function: In lib/functions/buildFileList.sh, create AddTo<Language name>FileArrays (where <Language name> is lowercase). This function should append the file to all relevant language arrays.
2. Export the function: Add export -f AddTo<Language name>FileArrays at the bottom of lib/functions/buildFileList.sh.
3. Refactor extension checks: Update the BuildFileArrays function to call your new helper instead of appending directly.
4. Extend CheckFileType: Add a case to the CheckFileType function to match the output of the file command.
5. Update tests: Add a case to CheckFileTypeTest in test/lib/buildFileListTest.sh.

# 1. Define helper
AddToPythonFileArrays() {
  local FILE="${1}"
  echo "${FILE}" >>"${FILE_ARRAYS_DIRECTORY_PATH}/file-array-PYTHON_BLACK"
  echo "${FILE}" >>"${FILE_ARRAYS_DIRECTORY_PATH}/file-array-PYTHON_FLAKE8"
}

# 2. Export helper
export -f AddToPythonFileArrays

# 3. Refactor extension check
elif [ "${FILE_TYPE}" == "py" ]; then
  AddToPythonFileArrays "${FILE}"
fi

# 4. Extend CheckFileType
*"Python script"*)
  FILE_TYPE_MESSAGE="Found Python script without extension: ${FILE}"
  AddToPythonFileArrays "${FILE}"
  ;;