Support for language annotations like /* bash*/

that should remain as block comments when directly preceding string literals,
while other block comments get converted to line comments.

- Detect language annotations: single-line, non-doc comments with valid language identifiers
- Preserve as `/* lang */` block comment syntax instead of converting to `# lang` line comments
- Works with both regular strings `"..."` and indented strings `''...''`

Author: dyegoaurelio

src/Nixfmt/Lexer.hs

@@ -6,11 +6,13 @@
 module Nixfmt.Lexer (lexeme, pushTrivia, takeTrivia, whole) where
 
 import Control.Monad.State.Strict (MonadState, evalStateT, get, modify, put)
-import Data.Char (isSpace)
+import Data.Char (isAlphaNum, isSpace)
+import Data.Functor (($>))
 import Data.List (dropWhileEnd)
 import Data.Maybe (fromMaybe)
 import Data.Text as Text (
   Text,
+  all,
   isPrefixOf,
   length,
   lines,
@@ -43,6 +45,7 @@ import Text.Megaparsec (
   chunk,
   getSourcePos,
   hidden,
+  lookAhead,
   many,
   manyTill,
   notFollowedBy,
@@ -59,6 +62,8 @@ data ParseTrivium
     PTLineComment Text Pos
   | -- Track whether it is a doc comment
     PTBlockComment Bool [Text]
+  | -- | Language annotation like /* lua */ (single line, non-doc)
+    PTLanguageAnnotation Text
   deriving (Show)
 
 preLexeme :: Parser a -> Parser a
@@ -127,6 +132,30 @@ blockComment = try $ preLexeme $ do
     commonIndentationLength :: Int -> [Text] -> Int
     commonIndentationLength = foldr (min . Text.length . Text.takeWhile (== ' '))
 
+languageAnnotation :: Parser ParseTrivium
+languageAnnotation = try $ do
+  -- Parse a block comment and extract its content
+  PTBlockComment False [content] <- blockComment
+  isStringDelimiterNext <- lookAhead isNextStringDelimiter
+
+  if isStringDelimiterNext && isValidLanguageIdentifier content
+    then return (PTLanguageAnnotation (strip content))
+    else fail "Not a language annotation"
+  where
+    -- Check if a text is a valid language identifier for language annotations
+    isValidLanguageIdentifier txt =
+      let stripped = strip txt
+      in not (Text.null stripped)
+          && Text.length stripped <= 30 -- TODO: make configurable or remove limit
+          && Text.all (\c -> isAlphaNum c || c `elem` ['-', '+', '.', '_', '$', '{', '}']) stripped
+
+    -- Parser to peek at the next token to see if it's a string delimiter (" or '')
+    isNextStringDelimiter = do
+      _ <- manyP isSpace -- Skip any remaining whitespace
+      (chunk "\"" $> True)
+        <|> (chunk "''" $> True)
+        <|> pure False
+
 -- This should be called with zero or one elements, as per `span isTrailing`
 convertTrailing :: [ParseTrivium] -> Maybe TrailingComment
 convertTrailing = toMaybe . join . map toText
@@ -148,6 +177,7 @@ convertLeading =
         PTBlockComment _ [] -> []
         PTBlockComment False [c] -> [LineComment $ " " <> strip c]
         PTBlockComment isDoc cs -> [BlockComment isDoc cs]
+        PTLanguageAnnotation c -> [LanguageAnnotation c]
     )
 
 isTrailing :: ParseTrivium -> Bool
@@ -169,7 +199,7 @@ convertTrivia pts nextCol =
       _ -> (convertTrailing trailing, convertLeading leading)
 
 trivia :: Parser [ParseTrivium]
-trivia = many $ hidden $ lineComment <|> blockComment <|> newlines
+trivia = many $ hidden $ languageAnnotation <|> lineComment <|> blockComment <|> newlines
 
 -- The following primitives to interact with the state monad that stores trivia
 -- are designed to prevent trivia from being dropped or duplicated by accident.

src/Nixfmt/Pretty.hs

@@ -86,6 +86,7 @@ instance Pretty TrailingComment where
 instance Pretty Trivium where
   pretty EmptyLine = emptyline
   pretty (LineComment c) = comment ("#" <> c) <> hardline
+  pretty (LanguageAnnotation lang) = comment ("/* " <> lang <> " */") <> hardspace
   pretty (BlockComment isDoc c) =
     comment (if isDoc then "/**" else "/*")
       <> hardline
@@ -105,10 +106,23 @@ instance (Pretty a) => Pretty (Item a) where
 
 -- For lists, attribute sets and let bindings
 prettyItems :: (Pretty a) => Items a -> Doc
-prettyItems (Items items) = sepBy hardline items
+prettyItems (Items items) = go items
+  where
+    go [] = mempty
+    go [item] = pretty item
+    -- Special case: language annotation comment followed by string item
+    go (Comments [LanguageAnnotation lang] : Item stringItem : rest) =
+      pretty (LanguageAnnotation lang)
+        <> hardspace
+        <> group stringItem
+        <> if null rest then mempty else hardline <> go rest
+    go (item : rest) =
+      pretty item <> if null rest then mempty else hardline <> go rest
 
 instance Pretty [Trivium] where
   pretty [] = mempty
+  -- Special case: if trivia consists only of a single language annotation, render it inline without a preceding hardline
+  pretty [langAnnotation@(LanguageAnnotation _)] = pretty langAnnotation
   pretty trivia = hardline <> hcat trivia
 
 instance (Pretty a) => Pretty (Ann a) where

src/Nixfmt/Types.hs

@@ -72,6 +72,8 @@ data Trivium
   | -- Multi-line comments with /* or /**. Multiple # comments are treated as a list of `LineComment`.
     -- The bool indicates a doc comment (/**)
     BlockComment Bool [Text]
+  | -- | Language annotation comments like /* lua */ that should remain as block comments before strings
+    LanguageAnnotation Text
   deriving (Eq, Show)
 
 type Trivia = [Trivium]