Migrate from old using_directives to Scala-rewritten directives-parser module (#4192)

* Migrate from old `using_directives` to Scala-rewritten `directives-parser` module

* Refactor tests

* Handle edge cases

* Include `directives-parser` module in `AGENTS.md`

Author: Gedochao

AGENTS.md

@@ -51,6 +51,8 @@ Modules live under `modules/`. The dependency graph flows roughly as:
 
 ```
 specification-level → config → core → options → directives → build-module → cli
+                                                    ↑
+                                          directives-parser
 ```
 
 ### Module overview
@@ -64,6 +66,7 @@ The list below may not be exhaustive — check `modules/` and `build.mill` for t
 | `build-macros`                                | Compile-time macros (e.g. `EitherCps`).                                                                          |
 | `core`                                        | Core types: `Inputs`, `Sources`, build constants, Bloop integration, JVM/JS/Native tooling.                      |
 | `options`                                     | `BuildOptions`, `SharedOptions`, and all option types.                                                           |
+| `directives-parser`                           | Pure Scala 3 parser for `//> using` directive syntax: comment extraction, lexing, and parsing into AST nodes.    |
 | `directives`                                  | Using directive handlers — the bridge between `//> using` directives and `BuildOptions`.                         |
 | `build-module` (aliased from `build` in mill) | The main build pipeline: preprocessing, compilation, post-processing. Most business logic lives here.            |
 | `cli`                                         | Command definitions, argument parsing (CaseApp), the `ScalaCli` entry point. Packaged as the native image.       |
@@ -106,9 +109,9 @@ Using directives are in-source configuration comments:
 //> using test.dep org.scalameta::munit::1.1.1
 ```
 
-Directives are parsed by `using_directives`, then `ExtractedDirectives` → `DirectivesPreprocessor` → `BuildOptions`/
-`BuildRequirements`. **CLI options override directive values.** To add a new directive,
-see [agentskills/adding-directives/](agentskills/adding-directives/SKILL.md).
+Directives are parsed by the `directives-parser` module (`CommentExtractor` → `Lexer` → `Parser`), then
+`ExtractedDirectives` → `DirectivesPreprocessor` → `BuildOptions`/`BuildRequirements`. **CLI options override directive
+values.** To add a new directive, see [agentskills/adding-directives/](agentskills/adding-directives/SKILL.md).
 
 ## Testing
 

build.mill

@@ -98,6 +98,8 @@ object `specification-level` extends Cross[SpecificationLevel](Scala.scala3MainV
     with CrossScalaDefaultToInternal
 object `build-macros` extends Cross[BuildMacros](Scala.scala3MainVersions)
     with CrossScalaDefaultToInternal
+object `directives-parser` extends Cross[DirectivesParserModule](Scala.scala3MainVersions)
+    with CrossScalaDefaultToInternal
 object config extends Cross[Config](Scala.scala3MainVersions)
     with CrossScalaDefaultToInternal
 object options extends Cross[Options](Scala.scala3MainVersions)
@@ -616,7 +618,8 @@ trait Directives extends ScalaCliCrossSbtModule
     options(crossScalaVersion),
     core(crossScalaVersion),
     `build-macros`(crossScalaVersion),
-    `specification-level`(crossScalaVersion)
+    `specification-level`(crossScalaVersion),
+    `directives-parser`(crossScalaVersion)
   )
   override def scalacOptions: T[Seq[String]] = Task {
     super.scalacOptions() ++ asyncScalacOptions(crossScalaVersion)
@@ -630,8 +633,7 @@ trait Directives extends ScalaCliCrossSbtModule
     // Deps.asm,
     Deps.bloopConfig,
     Deps.jsoniterCore,
-    Deps.pprint,
-    Deps.usingDirectives
+    Deps.pprint
   )
 
   override def repositoriesTask: Task[Seq[Repository]] =
@@ -806,6 +808,16 @@ trait Build extends ScalaCliCrossSbtModule
   }
 }
 
+trait DirectivesParserModule extends ScalaCliCrossSbtModule
+    with ScalaCliPublishModule
+    with HasTests
+    with ScalaCliScalafixModule
+    with LocatedInModules {
+  override def crossScalaVersion: String = crossValue
+
+  object test extends ScalaCliTests with ScalaCliScalafixModule
+}
+
 trait SpecificationLevel extends ScalaCliCrossSbtModule
     with ScalaCliPublishModule
     with LocatedInModules {
@@ -1024,6 +1036,9 @@ trait CliIntegration extends SbtModule
   )
 
   trait IntegrationScalaTests extends super.ScalaCliTests with ScalaCliScalafixModule {
+    override def moduleDeps: Seq[JavaModule] = super.moduleDeps ++ Seq(
+      `directives-parser`(sv)
+    )
     override def mvnDeps: T[Seq[Dep]] = super.mvnDeps() ++ Seq(
       Deps.bsp4j,
       Deps.coursier
@@ -1032,8 +1047,7 @@ trait CliIntegration extends SbtModule
       Deps.jsoniterCore,
       Deps.libsodiumjni,
       Deps.pprint,
-      Deps.slf4jNop,
-      Deps.usingDirectives
+      Deps.slf4jNop
     )
     override def compileMvnDeps: T[Seq[Dep]] = super.compileMvnDeps() ++ Seq(
       Deps.jsoniterMacros

modules/build/src/main/scala/scala/build/preprocessing/CustomDirectivesReporter.scala

@@ -1,17 +1,12 @@
 package scala.build.preprocessing
 
-import com.virtuslab.using_directives.UsingDirectivesProcessor
-import com.virtuslab.using_directives.custom.model.{BooleanValue, EmptyValue, StringValue, Value}
-import com.virtuslab.using_directives.custom.utils.ast.*
-
 import scala.annotation.targetName
 import scala.build.errors.*
 import scala.build.options.SuppressWarningOptions
-import scala.build.preprocessing.UsingDirectivesOps.*
 import scala.build.preprocessing.directives.StrictDirective
 import scala.build.{Logger, Position}
+import scala.cli.parse.{DiagnosticSeverity, DirectiveValue, UsingDirectivesParser}
 import scala.collection.mutable
-import scala.jdk.CollectionConverters.*
 
 case class ExtractedDirectives(
   directives: Seq[StrictDirective],
@@ -33,65 +28,68 @@ object ExtractedDirectives {
     logger: Logger,
     maybeRecoverOnError: BuildException => Option[BuildException]
   ): Either[BuildException, ExtractedDirectives] = {
-    val errors   = new mutable.ListBuffer[Diagnostic]
-    val reporter = CustomDirectivesReporter
-      .create(path) {
-        case diag
-            if diag.severity == Severity.Warning &&
-            diag.message.toLowerCase.contains("deprecated") &&
-            suppressWarningOptions.suppressDeprecatedFeatureWarning.getOrElse(false) =>
-          () // skip deprecated feature warnings if suppressed
-        case diag if diag.severity == Severity.Warning =>
-          logger.log(Seq(diag))
-        case diag => errors += diag
-      }
-    val processor                = new UsingDirectivesProcessor(reporter)
-    val allDirectives            = processor.extract(contentChars).asScala
+    val result           = UsingDirectivesParser.parse(contentChars)
+    val diagnosticErrors = mutable.ListBuffer.empty[Diagnostic]
+
+    for diag <- result.diagnostics do
+      val positions = diag.position.map { p =>
+        Position.File(path, (p.line, p.column), (p.line, p.column))
+      }.toSeq
+
+      if diag.severity == DiagnosticSeverity.Warning then
+        if diag.message.toLowerCase.contains("deprecated") &&
+          suppressWarningOptions.suppressDeprecatedFeatureWarning.getOrElse(false)
+        then () // skip
+        else logger.log(Seq(Diagnostic(diag.message, Severity.Warning, positions)))
+      else
+        diagnosticErrors += Diagnostic(diag.message, Severity.Error, positions)
+
     val malformedDirectiveErrors =
-      errors.map(diag => new MalformedDirectiveError(diag.message, diag.positions)).toSeq
+      diagnosticErrors
+        .map(diag => new MalformedDirectiveError(diag.message, diag.positions))
+        .toSeq
+
     val maybeCompositeMalformedDirectiveError =
-      if (malformedDirectiveErrors.nonEmpty)
+      if malformedDirectiveErrors.nonEmpty then
         maybeRecoverOnError(CompositeBuildException(malformedDirectiveErrors))
       else None
-    if (malformedDirectiveErrors.isEmpty || maybeCompositeMalformedDirectiveError.isEmpty) {
 
-      val directivesOpt         = allDirectives.headOption
-      val directivesPositionOpt = directivesOpt match {
-        case Some(directives)
-            if directives.containsTargetDirectives ||
-            directives.isEmpty => None
-        case Some(directives) => Some(directives.getPosition(path))
-        case None             => None
-      }
+    if malformedDirectiveErrors.isEmpty || maybeCompositeMalformedDirectiveError.isEmpty then
+      val directives = result.directives
+
+      val containsTargetDirectives = directives.exists(_.key.startsWith("target."))
 
-      val strictDirectives = directivesOpt.toSeq.flatMap { directives =>
-        def toStrictValue(value: UsingValue): Seq[Value[?]] = value match {
-          case uvs: UsingValues   => uvs.values.asScala.toSeq.flatMap(toStrictValue)
-          case el: EmptyLiteral   => Seq(EmptyValue(el))
-          case sl: StringLiteral  => Seq(StringValue(sl.getValue(), sl))
-          case bl: BooleanLiteral => Seq(BooleanValue(bl.getValue(), bl))
-        }
-        def toStrictDirective(ud: UsingDef) =
-          StrictDirective(
-            ud.getKey(),
-            toStrictValue(ud.getValue()),
-            ud.getPosition().getColumn(),
-            ud.getPosition().getLine()
-          )
+      val directivesPositionOpt =
+        if containsTargetDirectives || directives.isEmpty then None
+        else
+          val lastDirective     = directives.last
+          val (endLine, endCol) = lastDirective.values.lastOption match
+            case Some(sv: DirectiveValue.StringVal) if sv.isQuoted =>
+              (sv.pos.line, sv.pos.column + sv.value.length + 2)
+            case Some(sv: DirectiveValue.StringVal) =>
+              (sv.pos.line, sv.pos.column + sv.value.length)
+            case Some(bv: DirectiveValue.BoolVal) =>
+              (bv.pos.line, bv.pos.column + bv.value.toString.length)
+            case Some(ev: DirectiveValue.EmptyVal) =>
+              (ev.pos.line, ev.pos.column)
+            case None =>
+              val kp = lastDirective.keyPosition
+              (kp.line, kp.column + lastDirective.key.length)
+          Some(Position.File(path, (0, 0), (endLine, endCol), result.codeOffset))
 
-        directives.getAst match
-          case uds: UsingDefs => uds.getUsingDefs.asScala.toSeq.map(toStrictDirective)
-          case ud: UsingDef   => Seq(toStrictDirective(ud))
-          case _ => Nil // There should be nothing else here other than UsingDefs or UsingDef
+      val strictDirectives = directives.map { ud =>
+        StrictDirective(
+          ud.key,
+          ud.values,
+          ud.keyPosition.column,
+          ud.keyPosition.line
+        )
       }
 
       Right(ExtractedDirectives(strictDirectives.reverse, directivesPositionOpt))
-    }
     else
-      maybeCompositeMalformedDirectiveError match {
+      maybeCompositeMalformedDirectiveError match
         case Some(e) => Left(e)
         case None    => Right(ExtractedDirectives.empty)
-      }
   }
-
 }