Merge remote-tracking branch 'oxsecirity/main' into features/dotnet-u…

…pgrade-proposed-changes

# Conflicts:
#	CHANGELOG.md
#	Dockerfile
#	flavors/dotnet/Dockerfile
#	megalinter/descriptors/csharp.megalinter-descriptor.yml

.automation/build.py

@@ -721,7 +721,7 @@ def generate_documentation():
         + "code**, **IAC**, **configuration**, and **scripts** in your repository "
         + "sources, to **ensure all your projects "
         + "sources are clean and formatted** whatever IDE/toolbox is used by "
-        + "their developers, powered by [**OX security**](https://www.ox.security/?ref=megalinter).\n\n"
+        + "their developers, powered by [**OX Security**](https://www.ox.security/?ref=megalinter).\n\n"
         + f"Supporting [**{len(linters_by_type['language'])}** languages]"
         + "(#languages), "
         + f"[**{len(linters_by_type['format'])}** formats](#formats), "
@@ -767,7 +767,16 @@ def generate_documentation():
 def generate_descriptor_documentation(descriptor):
     descriptor_file = f"{descriptor.get('descriptor_id').lower()}.yml"
     descriptor_url = f"{URL_ROOT}/megalinter/descriptors/{descriptor_file}"
+    linter_names = [
+        linter.get("linter_name") for linter in descriptor.get("linters", [])
+    ]
+    is_are = "is" if len(linter_names) == 1 else "are"
     descriptor_md = [
+        "---",
+        f"title: {descriptor.get('descriptor_id')} linters in MegaLinter",
+        f"description: {', '.join(linter_names)} {is_are} available to analyze "
+        f"{descriptor.get('descriptor_id')} files in MegaLinter",
+        "---",
         "<!-- markdownlint-disable MD003 MD020 MD033 MD041 -->",
         f"<!-- {'@'}generated by .automation/build.py, please do not update manually -->",
         f"<!-- Instead, update descriptor file at {descriptor_url} -->",
@@ -872,6 +881,11 @@ def generate_flavor_documentation(flavor_id, flavor, linters_tables_md):
         f"![Docker Pulls]({BASE_SHIELD_COUNT_LINK}/" f"{ML_DOCKER_IMAGE}-{flavor_id})"
     )
     flavor_doc_md = [
+        "---",
+        f"title: {flavor_id} flavor in MegaLinter",
+        f"description: {flavor_id} flavor is an optimized MegaLinter with "
+        f"only linters related to {flavor_id} projects",
+        "---",
         f"# {flavor_id} MegaLinter Flavor",
         "",
         docker_image_badge,
@@ -940,22 +954,17 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
         "| :---: | ----------------- | -------------- | ------------ | :-----:  |",
     ]
     descriptor_linters = linters_by_type[type1]
-    prev_lang = ""
     for linter in descriptor_linters:
         lang_lower, linter_name_lower, descriptor_label = get_linter_base_info(linter)
-        if prev_lang != linter.descriptor_id and os.path.isfile(
-            REPO_ICONS + "/" + linter.descriptor_id.lower() + ".ico"
-        ):
+        if os.path.isfile(REPO_ICONS + "/" + linter.descriptor_id.lower() + ".ico"):
             icon_html = icon(
                 f"{DOCS_URL_RAW_ROOT}/assets/icons/{linter.descriptor_id.lower()}.ico",
                 "",
                 "",
                 descriptor_label,
                 32,
             )
-        elif prev_lang != linter.descriptor_id and os.path.isfile(
-            REPO_ICONS + "/default.ico"
-        ):
+        elif os.path.isfile(REPO_ICONS + "/default.ico"):
             icon_html = icon(
                 f"{DOCS_URL_RAW_ROOT}/assets/icons/default.ico",
                 "",
@@ -966,12 +975,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
         else:
             icon_html = "<!-- -->"
         descriptor_url = doc_url(f"{DOCS_URL_DESCRIPTORS_ROOT}/{lang_lower}.md")
-        descriptor_id_cell = (
-            f"[{descriptor_label}]({descriptor_url})"
-            if prev_lang != linter.descriptor_id
-            else ""
-        )
-        prev_lang = linter.descriptor_id
+        descriptor_id_cell = f"[{descriptor_label}]({descriptor_url})"
         # Build extra badges
         md_extras = []
         repo = get_github_repo(linter)
@@ -1001,6 +1005,12 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
 
         # Build individual linter doc
         linter_doc_md = [
+            "---",
+            f"title: {linter.linter_name} configuration in MegaLinter",
+            f"description: How to use {linter.linter_name} (configure, "
+            "ignore files, ignore errors, help & version documentations)"
+            f" to analyze {linter.descriptor_id} files",
+            "---",
             "<!-- markdownlint-disable MD033 MD041 -->",
             f"<!-- {'@'}generated by .automation/build.py, please do not update manually -->",
         ]
@@ -1044,6 +1054,28 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
         else:
             linter_doc_md += [f"# {linter.linter_name} {badge}"]
 
+        # Indicate that a linter is disabled in this version
+        if hasattr(linter, "deprecated") and linter.deprecated is True:
+            linter_doc_md += [""]
+            linter_doc_md += ["> This linter has been deprecated.", ">"]
+
+            if (
+                hasattr(linter, "deprecated_description")
+                and linter.deprecated_description
+            ):
+                linter_doc_md += [
+                    "> ".join(
+                        ("> " + linter.deprecated_description.lstrip()).splitlines(True)
+                    ),
+                    ">",
+                ]
+
+            linter_doc_md += [
+                f"> You should disable {linter.linter_name} by adding it in DISABLE_LINTERS property.",
+                ">",
+                "> It will be maintained at least until the next major release.",
+            ]
+
         # Indicate that a linter is disabled in this version
         if hasattr(linter, "disabled") and linter.disabled is True:
             linter_doc_md += [""]
@@ -1224,12 +1256,25 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
             )
         # cli_lint_mode can be overridden by user config if the descriptor cli_lint_mode is not "project"
         if linter.cli_lint_mode != "project":
-            linter_doc_md += [
+            cli_lint_mode_doc_md = (
                 f"| {linter.name}_CLI_LINT_MODE | Override default CLI lint mode<br/>"
-                f"- `file`: Calls the linter for each file<br/>"
-                "- `list_of_files`: Call the linter with the list of files as argument<br/>"
-                f"- `project`: Call the linter from the root of the project | `{linter.cli_lint_mode}` |"
-            ]
+            )
+            cli_lint_mode_doc_md += "- `file`: Calls the linter for each file<br/>"
+
+            if linter.cli_lint_mode == "file":
+                enum = ["file", "project"]
+            else:
+                enum = ["file", "list_of_files", "project"]
+
+                cli_lint_mode_doc_md += "- `list_of_files`: Call the linter with the list of files as argument<br/>"
+
+            cli_lint_mode_doc_md += (
+                "- `project`: Call the linter from the root of the project"
+            )
+            cli_lint_mode_doc_md += f" | `{linter.cli_lint_mode}` |"
+
+            linter_doc_md += [cli_lint_mode_doc_md]
+
             add_in_config_schema_file(
                 [
                     [
@@ -1239,7 +1284,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
                             "type": "string",
                             "title": f"{linter.name}: Override default cli lint mode",
                             "default": linter.cli_lint_mode,
-                            "enum": ["file", "list_of_files", "project"],
+                            "enum": enum,
                         },
                     ]
                 ]
@@ -1963,13 +2008,43 @@ def replace_in_file(file_path, start, end, content, add_new_line=True):
     # Read in the file
     with open(file_path, "r", encoding="utf-8") as file:
         file_content = file.read()
+    # Detect markdown headers if in replacement
+    header_content = None
+    header_matches = re.findall(
+        r"<!-- markdown-headers\n(.*)\n-->", content, re.MULTILINE | re.DOTALL
+    )
+    if header_matches and len(header_matches) > 0:
+        # Get text between markdown-headers tag
+        header_content = header_matches[0]
+        content = re.sub(
+            r"<!-- markdown-headers\n.*?\n-->", "", content, 1, re.MULTILINE | re.DOTALL
+        )[1:]
     # Replace the target string
     if add_new_line is True:
         replacement = f"{start}\n{content}\n{end}"
     else:
         replacement = f"{start}{content}{end}"
     regex = rf"{start}([\s\S]*?){end}"
-    file_content = re.sub(regex, replacement, file_content, re.DOTALL)
+    file_content = re.sub(regex, replacement, file_content, 1, re.DOTALL)
+    # Add / replace header if necessary
+    if header_content is not None:
+        existing_header_matches = re.findall(
+            r"---\n(.*)\n---", file_content, re.MULTILINE | re.DOTALL
+        )
+        if (
+            existing_header_matches
+            and len(existing_header_matches) > 0
+            and file_content.startswith("---")
+        ):
+            file_content = re.sub(
+                r"---\n.*?\n---",
+                header_content,
+                file_content,
+                1,
+                re.MULTILINE | re.DOTALL,
+            )
+        else:
+            file_content = header_content + "\n" + file_content
     # Write the file out again
     with open(file_path, "w", encoding="utf-8") as file:
         file.write(file_content)
@@ -2040,7 +2115,7 @@ def move_to_file(file_path, start, end, target_file, keep_in_source=False):
     else:
         bracket_content = ""
     if keep_in_source is False:
-        file_content = re.sub(regex, replacement, file_content, re.DOTALL)
+        file_content = re.sub(regex, replacement, file_content, 1, re.DOTALL)
     # Write the file out again
     with open(file_path, "w", encoding="utf-8") as file:
         file.write(file_content)
@@ -2192,10 +2267,10 @@ def finalize_doc_build():
         "<!-- mega-linter-badges-start -->",
         "<!-- mega-linter-badges-end -->",
         """![GitHub release](https://img.shields.io/github/v/release/oxsecurity/megalinter?sort=semver&color=%23FD80CD)
-[![Docker Pulls](https://img.shields.io/badge/docker%20pulls-3.7M-blue?color=%23FD80CD)](https://megalinter.github.io/flavors/)
+[![Docker Pulls](https://img.shields.io/badge/docker%20pulls-3.8M-blue?color=%23FD80CD)](https://megalinter.github.io/flavors/)
 [![Downloads/week](https://img.shields.io/npm/dw/mega-linter-runner.svg?color=%23FD80CD)](https://npmjs.org/package/mega-linter-runner)
 [![GitHub stars](https://img.shields.io/github/stars/oxsecurity/megalinter?cacheSeconds=3600&color=%23FD80CD)](https://github.com/oxsecurity/megalinter/stargazers/)
-[![Dependents](https://img.shields.io/static/v1?label=Used%20by&message=1690&color=informational&logo=slickpic)](https://github.com/oxsecurity/megalinter/network/dependents)
+[![Dependents](https://img.shields.io/static/v1?label=Used%20by&message=1690&color=%23FD80CD&logo=slickpic)](https://github.com/oxsecurity/megalinter/network/dependents)
 [![GitHub contributors](https://img.shields.io/github/contributors/oxsecurity/megalinter.svg?color=%23FD80CD)](https://github.com/oxsecurity/megalinter/graphs/contributors/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square&color=%23FD80CD)](http://makeapullrequest.com)""",  # noqa: E501
     )
@@ -2881,6 +2956,7 @@ def update_dependents_info():
     generate_linter_dockerfiles()
     generate_linter_test_classes()
     if UPDATE_DOC is True:
+        logging.info("Running documentation generators...")
         refresh_users_info()
         generate_documentation()
         generate_documentation_all_linters()