From a41de55f1d6697dee6ee3bf0af96a2d458ccac35 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 25 Jan 2025 14:17:27 +1300
Subject: [PATCH] cmdref: Export internal_flag to json

Commands flagged as internal will display a warning, just like experimental commands.
Drop `passes/tests` group in favour of `internal` group, which is automatically assigned for any command without an assigned group which is flagged as internal.
---
 docs/source/cmd/index_internal.rst     |  5 +++++
 docs/source/cmd/index_passes_tests.rst |  5 -----
 docs/source/cmd_ref.rst                |  1 +
 docs/util/newcmdref.py                 |  9 ++++++++-
 kernel/register.cc                     | 10 +++++-----
 5 files changed, 19 insertions(+), 11 deletions(-)
 create mode 100644 docs/source/cmd/index_internal.rst
 delete mode 100644 docs/source/cmd/index_passes_tests.rst

diff --git a/docs/source/cmd/index_internal.rst b/docs/source/cmd/index_internal.rst
new file mode 100644
index 00000000000..c1b7f5eb8f4
--- /dev/null
+++ b/docs/source/cmd/index_internal.rst
@@ -0,0 +1,5 @@
+internal
+------------------
+
+.. autocmdgroup:: internal
+   :members:
diff --git a/docs/source/cmd/index_passes_tests.rst b/docs/source/cmd/index_passes_tests.rst
deleted file mode 100644
index 72453f55ffe..00000000000
--- a/docs/source/cmd/index_passes_tests.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-passes/tests
-------------------
-
-.. autocmdgroup:: passes/tests
-   :members:
diff --git a/docs/source/cmd_ref.rst b/docs/source/cmd_ref.rst
index bc0707d677d..37b6966efcd 100644
--- a/docs/source/cmd_ref.rst
+++ b/docs/source/cmd_ref.rst
@@ -19,4 +19,5 @@ Command line reference
    /cmd/index_formal
    /cmd/index_passes*
    /cmd/index_techlibs
+   /cmd/index_internal
    /cmd/index_other
diff --git a/docs/util/newcmdref.py b/docs/util/newcmdref.py
index 07c93c0d1e4..61753fa57a5 100644
--- a/docs/util/newcmdref.py
+++ b/docs/util/newcmdref.py
@@ -53,6 +53,7 @@ class YosysCmd:
     source_line: int
     source_func: str
     experimental_flag: bool
+    internal_flag: bool
 
     def __init__(
             self,
@@ -62,7 +63,8 @@ def __init__(
             source_file: str = "",
             source_line: int = 0,
             source_func: str = "",
-            experimental_flag: bool = False
+            experimental_flag: bool = False,
+            internal_flag: bool = False,
     ) -> None:
         self.name = name
         self.title = title
@@ -72,6 +74,7 @@ def __init__(
         self.source_line = source_line
         self.source_func = source_func
         self.experimental_flag = experimental_flag
+        self.internal_flag = internal_flag
     
 class YosysCmdGroupDocumenter(Documenter):
     objtype = 'cmdgroup'
@@ -344,6 +347,10 @@ def add_content(self, more_content: Any | None) -> None:
             self.add_line(f'.. warning:: This command is experimental', source_name, source_line)
             self.add_line('\n', source_name)
 
+        if self.object.internal_flag:
+            self.add_line(f'.. warning:: This command is intended for internal developer use only', source_name, source_line)
+            self.add_line('\n', source_name)
+
         def render(content_list: YosysCmdContentListing, indent: int=0):
             content_source = content_list.source_file or source_name
             indent_str = '   '*indent
diff --git a/kernel/register.cc b/kernel/register.cc
index f84d1b91c61..2e6b45610e8 100644
--- a/kernel/register.cc
+++ b/kernel/register.cc
@@ -938,7 +938,6 @@ struct HelpPass : public Pass {
 			auto name = it.first;
 			auto pass = it.second;
 			auto title = pass->short_help;
-			auto experimental_flag = pass->experimental_flag;
 
 			auto cmd_help = PrettyHelp();
 			auto has_pretty_help = pass->formatted_help();
@@ -1078,7 +1077,9 @@ struct HelpPass : public Pass {
 			if (!cmd_help.has_group()) {
 				string source_file = pass->location.file_name();
 				bool has_source = source_file.compare("unknown") != 0;
-				if (source_file.find("backends/") == 0 || (!has_source && name.find("read_") == 0))
+				if (pass->internal_flag)
+					cmd_help.group = "internal";
+				else if (source_file.find("backends/") == 0 || (!has_source && name.find("read_") == 0))
 					cmd_help.group = "backends";
 				else if (source_file.find("frontends/") == 0 || (!has_source && name.find("write_") == 0))
 					cmd_help.group = "frontends";
@@ -1102,8 +1103,6 @@ struct HelpPass : public Pass {
 					cmd_help.group = "passes/opt";
 				else if (name.find("proc") == 0)
 					cmd_help.group = "passes/proc";
-				else if (name.find("test") == 0)
-					cmd_help.group = "passes/tests";
 			}
 
 			if (groups.count(cmd_help.group) == 0) {
@@ -1122,7 +1121,8 @@ struct HelpPass : public Pass {
 			json.entry("source_file", pass->location.file_name());
 			json.entry("source_line", pass->location.line());
 			json.entry("source_func", pass->location.function_name());
-			json.entry("experimental_flag", experimental_flag);
+			json.entry("experimental_flag", pass->experimental_flag);
+			json.entry("internal_flag", pass->internal_flag);
 			json.end_object();
 		}
 		json.end_object();