From fecf423d6d4a6cb5a31445a4bdb75b5906658be5 Mon Sep 17 00:00:00 2001
From: Ruud Senden <8635138+rsenden@users.noreply.github.com>
Date: Fri, 25 Oct 2024 14:49:54 +0200
Subject: [PATCH] fix: Fix fcli command links in action documentation (fixes
 #622)

---
 .../cmd/AbstractActionAsciidocCommand.java    | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/fcli-core/fcli-common/src/main/java/com/fortify/cli/common/action/cli/cmd/AbstractActionAsciidocCommand.java b/fcli-core/fcli-common/src/main/java/com/fortify/cli/common/action/cli/cmd/AbstractActionAsciidocCommand.java
index cffb960ee2..02ceecd9ab 100644
--- a/fcli-core/fcli-common/src/main/java/com/fortify/cli/common/action/cli/cmd/AbstractActionAsciidocCommand.java
+++ b/fcli-core/fcli-common/src/main/java/com/fortify/cli/common/action/cli/cmd/AbstractActionAsciidocCommand.java
@@ -18,7 +18,6 @@
 import java.nio.file.StandardOpenOption;
 import java.util.HashSet;
 import java.util.Set;
-import java.util.function.Function;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
@@ -116,14 +115,28 @@ private final String generateOptionDescription(IOptionDescriptor descriptor) {
     
     private final String addLinks(String contents) {
         if ( manpageDir==null ) { return contents; }
+        // TODO Do we want to automatically insert fcli links (which could potentially lead to bugs as seen with 
+        //      https://github.com/fortify/fcli/issues/622), or should we allow Markdown syntax in action descriptions?
+        //      We could either add support for new markdownDescription properties, or allow Markdown in existing
+        //      description properties and clean this up in the 'action help' command.
         var manPages = listDir(manpageDir).stream().filter(s->s.matches("fcli-[\\w-]+-[\\w-]+-[\\w-]+.adoc"))
             .map(s->s.replaceAll("\\.adoc", ""))
+            .sorted((a,b)->Integer.compare(a.length(), b.length())) // In case of overlapping names, we need to replace longest matching name
             .collect(Collectors.toSet());
         for ( var manPage : manPages ) {
             var pattern = manPage.replace("-", "[ -]");
             var replacement = String.format("link:manpage/%s.html[$1]", manPage);
-            contents = contents.replaceAll("(?<!`)("+pattern+")", replacement);
-            contents = contents.replaceAll("(`"+pattern+".*`)", replacement);
+            if ( manPage.matches("fcli-[a-z]+-action-run") ) {
+                // Replace 'fcli <module> action run' references in synopsis
+                contents = contents.replaceAll("("+pattern+")", replacement);  
+            } else {
+                // Replace literal 'fcli *' references embedded in backticks, if not preceded by '['
+                // as that (likely) means we already generated a link for a longer command name.
+                // See https://github.com/fortify/fcli/issues/622 for example. The backticks need to
+                // go into the link text (as otherwise link:... would be rendered literally), so we
+                // need to include the full text between the backticks in the link text.
+                contents = contents.replaceAll("(?<!\\[)(`"+pattern+".*`)", replacement);
+            }
         }
         return contents;
     }