@hivehub/rulebook 5.4.1 → 5.5.1

package/templates/languages/SCALA.md

@@ -1,348 +1,348 @@
-<!-- SCALA:START -->
-# Scala Project Rules
-
-## Agent Automation Commands
-
-**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
-
-```bash
-# Complete quality check sequence:
-sbt scalafmtCheckAll      # Format check
-sbt scalafix --check      # Linting
-sbt compile               # Compilation check
-sbt test                  # All tests (100% pass)
-sbt coverage              # Coverage (95%+ required)
-
-# Security audit:
-sbt dependencyCheck       # Vulnerability scan
-sbt dependencyUpdates     # Check outdated deps
-```
-
-## Scala Configuration
-
-**CRITICAL**: Use Scala 3.x with modern tooling and strict compiler flags.
-
-- **Version**: Scala 3.3+
-- **Build Tool**: sbt 1.9+ or Mill 0.11+
-- **Formatting**: scalafmt
-- **Linting**: scalafix + Wartremover
-- **Testing**: ScalaTest, MUnit, or Specs2
-
-### build.sbt Requirements
-
-```scala
-ThisBuild / organization := "com.yourcompany"
-ThisBuild / scalaVersion := "3.3.1"
-ThisBuild / version      := "0.1.0-SNAPSHOT"
-
-lazy val root = (project in file("."))
-  .settings(
-    name := "your-project",
-    
-    // Compiler options
-    scalacOptions ++= Seq(
-      "-encoding", "UTF-8",
-      "-feature",
-      "-language:implicitConversions",
-      "-unchecked",
-      "-Werror",
-      "-Wunused:all",
-      "-Wvalue-discard",
-      "-Xfatal-warnings"
-    ),
-    
-    // Dependencies
-    libraryDependencies ++= Seq(
-      "org.scala-lang" %% "scala3-library" % scalaVersion.value,
-      
-      // Test dependencies
-      "org.scalatest" %% "scalatest" % "3.2.17" % Test,
-      "org.scalatestplus" %% "scalacheck-1-17" % "3.2.17.0" % Test
-    ),
-    
-    // Test configuration
-    Test / testOptions += Tests.Argument("-oDF"),
-    Test / parallelExecution := false,
-    
-    // Coverage
-    coverageMinimumStmtTotal := 80,
-    coverageFailOnMinimum := true,
-    coverageHighlighting := true
-  )
-
-// Plugins
-addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.5.2")
-addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.11.1")
-addSbtPlugin("org.scoverage" % "sbt-scoverage" % "2.0.9")
-addSbtPlugin("org.wartremover" % "sbt-wartremover" % "3.1.6")
-```
-
-## Code Quality Standards
-
-### Mandatory Quality Checks
-
-**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
-
-**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
-
-```bash
-# Pre-Commit Checklist - sbt (MUST match .github/workflows/*.yml)
-
-# 1. Format check (matches workflow - use Check, not format!)
-sbt scalafmtCheckAll scalafmtSbtCheck
-
-# 2. Lint with scalafix (matches workflow - use --check!)
-sbt "scalafixAll --check"
-
-# 3. Compile with fatal warnings (matches workflow)
-sbt clean compile Test/compile
-
-# 4. Run Wartremover (matches workflow)
-sbt wartremoverCheck
-
-# 5. Run all tests (MUST pass 100% - matches workflow)
-sbt test
-
-# 6. Check coverage (MUST meet threshold - matches workflow)
-sbt clean coverage test coverageReport
-sbt coverageAggregate
-
-# If ANY fails: ❌ DO NOT COMMIT - Fix first!
-```
-
-**If ANY of these fail, you MUST fix the issues before committing.**
-
-**Why This Matters:**
-- Running different commands locally than in CI causes "works on my machine" failures
-- CI/CD workflows will fail if commands don't match
-- Example: Using `scalafmtAll` locally but `scalafmtCheckAll` in CI = failure
-- Example: Using `scalafixAll` (applies fixes) locally but `scalafixAll --check` in CI = failure
-- Example: Missing `wartremoverCheck` locally = CI catches code quality issues
-
-### Formatting with scalafmt
-
-- Configuration in `.scalafmt.conf`
-- Consistent formatting across project
-- Check in CI (don't auto-format)
-
-Example `.scalafmt.conf`:
-```conf
-version = "3.7.17"
-runner.dialect = scala3
-maxColumn = 100
-align.preset = more
-align.multiline = false
-assumeStandardLibraryStripMargin = true
-docstrings.style = Asterisk
-lineEndings = unix
-includeCurlyBraceInSelectChains = false
-danglingParentheses.preset = true
-spaces.inImportCurlyBraces = false
-optIn.annotationNewlines = true
-rewrite.rules = [
-  RedundantBraces,
-  RedundantParens,
-  PreferCurlyFors,
-  SortModifiers
-]
-```
-
-### Linting with Scalafix
-
-- Configuration in `.scalafix.conf`
-- Enforce code quality rules
-- Prevent common bugs
-
-Example `.scalafix.conf`:
-```conf
-rules = [
-  DisableSyntax,
-  LeakingImplicitClassVal,
-  NoAutoTupling,
-  NoValInForComprehension,
-  ProcedureSyntax,
-  RemoveUnused
-]
-
-DisableSyntax.noVars = true
-DisableSyntax.noThrows = true
-DisableSyntax.noNulls = true
-DisableSyntax.noReturns = true
-DisableSyntax.noWhileLoops = true
-DisableSyntax.noAsInstanceOf = true
-DisableSyntax.noIsInstanceOf = true
-DisableSyntax.noXml = true
-```
-
-### Testing
-
-- **Framework**: ScalaTest (recommended), MUnit, or Specs2
-- **Location**: `/src/test/scala` directory
-- **Coverage**: sbt-scoverage (80%+ threshold)
-- **Property Testing**: ScalaCheck
-
-Example ScalaTest:
-```scala
-import org.scalatest.flatspec.AnyFlatSpec
-import org.scalatest.matchers.should.Matchers
-import org.scalatest.BeforeAndAfterEach
-
-class DataProcessorSpec extends AnyFlatSpec with Matchers with BeforeAndAfterEach {
-  
-  var processor: DataProcessor = _
-  
-  override def beforeEach(): Unit = {
-    processor = new DataProcessor(threshold = 0.5)
-  }
-  
-  override def afterEach(): Unit = {
-    // Cleanup
-  }
-  
-  "DataProcessor" should "process valid input correctly" in {
-    val input = List(1, 2, 3, 4, 5)
-    val result = processor.process(input)
-    
-    result should not be empty
-    result.length should be > 0
-  }
-  
-  it should "handle empty input" in {
-    val result = processor.process(List.empty)
-    result shouldBe empty
-  }
-  
-  it should "throw exception on null input" in {
-    assertThrows[IllegalArgumentException] {
-      processor.process(null)
-    }
-  }
-}
-```
-
-Example with MUnit:
-```scala
-import munit.FunSuite
-
-class DataProcessorSuite extends FunSuite {
-  
-  test("process should handle valid input") {
-    val processor = new DataProcessor(threshold = 0.5)
-    val input = List(1, 2, 3)
-    val result = processor.process(input)
-    
-    assert(result.nonEmpty)
-    assertEquals(result.length, 3)
-  }
-  
-  test("process should handle empty input") {
-    val processor = new DataProcessor(threshold = 0.5)
-    val result = processor.process(List.empty)
-    
-    assert(result.isEmpty)
-  }
-}
-```
-
-## Type Safety
-
-- Use case classes for immutable data
-- Leverage sealed traits for ADTs
-- Use Option instead of null
-- Pattern matching for control flow
-
-Example:
-```scala
-// Sealed trait for ADT
-sealed trait Result[+A]
-case class Success[A](value: A) extends Result[A]
-case class Failure(error: String) extends Result[Nothing]
-
-// Case class for data
-case class User(
-  id: String,
-  name: String,
-  email: Option[String] = None,
-  age: Option[Int] = None
-)
-
-// Pattern matching
-def handleResult[A](result: Result[A]): String = result match {
-  case Success(value) => s"Got value: $value"
-  case Failure(error) => s"Error: $error"
-}
-
-// Option handling
-def getUserEmail(user: User): String = 
-  user.email.getOrElse("no-email@example.com")
-```
-
-## Functional Programming
-
-- Prefer immutability
-- Use pure functions
-- Avoid side effects
-- Use for-comprehensions for monadic operations
-
-Example:
-```scala
-// ✅ GOOD: Immutable, pure functions
-class DataProcessor(threshold: Double) {
-  def process(data: List[Int]): List[Int] = 
-    data.filter(_ > threshold)
-  
-  def transform(data: List[Int]): List[String] =
-    data.map(x => s"Value: $x")
-  
-  def pipeline(data: List[Int]): List[String] = for {
-    filtered <- Some(process(data))
-    transformed <- Some(transform(filtered))
-  } yield transformed
-}
-
-// ❌ BAD: Mutable, impure
-class DataProcessor(var threshold: Double) {
-  var results: List[Int] = List.empty  // Mutable state!
-  
-  def process(data: List[Int]): Unit = {  // Side effect!
-    results = data.filter(_ > threshold)
-    println(results)  // More side effects!
-  }
-}
-```
-
-## CI/CD Requirements
-
-Must include GitHub Actions workflows:
-
-1. **Testing** (`scala-test.yml`):
-   - Test on ubuntu-latest
-   - Scala versions: 3.3.x
-   - sbt test with coverage
-
-2. **Linting** (`scala-lint.yml`):
-   - scalafmtCheckAll
-   - scalafixAll --check
-   - wartremoverCheck
-
-3. **Build** (`scala-build.yml`):
-   - sbt compile
-   - sbt package
-   - Verify artifacts
-
-## Publishing
-
-### To Maven Central
-
-```bash
-# 1. Configure credentials in ~/.sbt/1.0/sonatype.sbt
-# 2. Update version
-# 3. Run quality checks
-sbt clean scalafmtCheckAll test
-
-# 4. Publish
-sbt publishSigned
-sbt sonatypeBundleRelease
-```
-
-<!-- SCALA:END -->
+<!-- SCALA:START -->
+# Scala Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+sbt scalafmtCheckAll      # Format check
+sbt scalafix --check      # Linting
+sbt compile               # Compilation check
+sbt test                  # All tests (100% pass)
+sbt coverage              # Coverage (95%+ required)
+
+# Security audit:
+sbt dependencyCheck       # Vulnerability scan
+sbt dependencyUpdates     # Check outdated deps
+```
+
+## Scala Configuration
+
+**CRITICAL**: Use Scala 3.x with modern tooling and strict compiler flags.
+
+- **Version**: Scala 3.3+
+- **Build Tool**: sbt 1.9+ or Mill 0.11+
+- **Formatting**: scalafmt
+- **Linting**: scalafix + Wartremover
+- **Testing**: ScalaTest, MUnit, or Specs2
+
+### build.sbt Requirements
+
+```scala
+ThisBuild / organization := "com.yourcompany"
+ThisBuild / scalaVersion := "3.3.1"
+ThisBuild / version      := "0.1.0-SNAPSHOT"
+
+lazy val root = (project in file("."))
+  .settings(
+    name := "your-project",
+    
+    // Compiler options
+    scalacOptions ++= Seq(
+      "-encoding", "UTF-8",
+      "-feature",
+      "-language:implicitConversions",
+      "-unchecked",
+      "-Werror",
+      "-Wunused:all",
+      "-Wvalue-discard",
+      "-Xfatal-warnings"
+    ),
+    
+    // Dependencies
+    libraryDependencies ++= Seq(
+      "org.scala-lang" %% "scala3-library" % scalaVersion.value,
+      
+      // Test dependencies
+      "org.scalatest" %% "scalatest" % "3.2.17" % Test,
+      "org.scalatestplus" %% "scalacheck-1-17" % "3.2.17.0" % Test
+    ),
+    
+    // Test configuration
+    Test / testOptions += Tests.Argument("-oDF"),
+    Test / parallelExecution := false,
+    
+    // Coverage
+    coverageMinimumStmtTotal := 80,
+    coverageFailOnMinimum := true,
+    coverageHighlighting := true
+  )
+
+// Plugins
+addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.5.2")
+addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.11.1")
+addSbtPlugin("org.scoverage" % "sbt-scoverage" % "2.0.9")
+addSbtPlugin("org.wartremover" % "sbt-wartremover" % "3.1.6")
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist - sbt (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow - use Check, not format!)
+sbt scalafmtCheckAll scalafmtSbtCheck
+
+# 2. Lint with scalafix (matches workflow - use --check!)
+sbt "scalafixAll --check"
+
+# 3. Compile with fatal warnings (matches workflow)
+sbt clean compile Test/compile
+
+# 4. Run Wartremover (matches workflow)
+sbt wartremoverCheck
+
+# 5. Run all tests (MUST pass 100% - matches workflow)
+sbt test
+
+# 6. Check coverage (MUST meet threshold - matches workflow)
+sbt clean coverage test coverageReport
+sbt coverageAggregate
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- Running different commands locally than in CI causes "works on my machine" failures
+- CI/CD workflows will fail if commands don't match
+- Example: Using `scalafmtAll` locally but `scalafmtCheckAll` in CI = failure
+- Example: Using `scalafixAll` (applies fixes) locally but `scalafixAll --check` in CI = failure
+- Example: Missing `wartremoverCheck` locally = CI catches code quality issues
+
+### Formatting with scalafmt
+
+- Configuration in `.scalafmt.conf`
+- Consistent formatting across project
+- Check in CI (don't auto-format)
+
+Example `.scalafmt.conf`:
+```conf
+version = "3.7.17"
+runner.dialect = scala3
+maxColumn = 100
+align.preset = more
+align.multiline = false
+assumeStandardLibraryStripMargin = true
+docstrings.style = Asterisk
+lineEndings = unix
+includeCurlyBraceInSelectChains = false
+danglingParentheses.preset = true
+spaces.inImportCurlyBraces = false
+optIn.annotationNewlines = true
+rewrite.rules = [
+  RedundantBraces,
+  RedundantParens,
+  PreferCurlyFors,
+  SortModifiers
+]
+```
+
+### Linting with Scalafix
+
+- Configuration in `.scalafix.conf`
+- Enforce code quality rules
+- Prevent common bugs
+
+Example `.scalafix.conf`:
+```conf
+rules = [
+  DisableSyntax,
+  LeakingImplicitClassVal,
+  NoAutoTupling,
+  NoValInForComprehension,
+  ProcedureSyntax,
+  RemoveUnused
+]
+
+DisableSyntax.noVars = true
+DisableSyntax.noThrows = true
+DisableSyntax.noNulls = true
+DisableSyntax.noReturns = true
+DisableSyntax.noWhileLoops = true
+DisableSyntax.noAsInstanceOf = true
+DisableSyntax.noIsInstanceOf = true
+DisableSyntax.noXml = true
+```
+
+### Testing
+
+- **Framework**: ScalaTest (recommended), MUnit, or Specs2
+- **Location**: `/src/test/scala` directory
+- **Coverage**: sbt-scoverage (80%+ threshold)
+- **Property Testing**: ScalaCheck
+
+Example ScalaTest:
+```scala
+import org.scalatest.flatspec.AnyFlatSpec
+import org.scalatest.matchers.should.Matchers
+import org.scalatest.BeforeAndAfterEach
+
+class DataProcessorSpec extends AnyFlatSpec with Matchers with BeforeAndAfterEach {
+  
+  var processor: DataProcessor = _
+  
+  override def beforeEach(): Unit = {
+    processor = new DataProcessor(threshold = 0.5)
+  }
+  
+  override def afterEach(): Unit = {
+    // Cleanup
+  }
+  
+  "DataProcessor" should "process valid input correctly" in {
+    val input = List(1, 2, 3, 4, 5)
+    val result = processor.process(input)
+    
+    result should not be empty
+    result.length should be > 0
+  }
+  
+  it should "handle empty input" in {
+    val result = processor.process(List.empty)
+    result shouldBe empty
+  }
+  
+  it should "throw exception on null input" in {
+    assertThrows[IllegalArgumentException] {
+      processor.process(null)
+    }
+  }
+}
+```
+
+Example with MUnit:
+```scala
+import munit.FunSuite
+
+class DataProcessorSuite extends FunSuite {
+  
+  test("process should handle valid input") {
+    val processor = new DataProcessor(threshold = 0.5)
+    val input = List(1, 2, 3)
+    val result = processor.process(input)
+    
+    assert(result.nonEmpty)
+    assertEquals(result.length, 3)
+  }
+  
+  test("process should handle empty input") {
+    val processor = new DataProcessor(threshold = 0.5)
+    val result = processor.process(List.empty)
+    
+    assert(result.isEmpty)
+  }
+}
+```
+
+## Type Safety
+
+- Use case classes for immutable data
+- Leverage sealed traits for ADTs
+- Use Option instead of null
+- Pattern matching for control flow
+
+Example:
+```scala
+// Sealed trait for ADT
+sealed trait Result[+A]
+case class Success[A](value: A) extends Result[A]
+case class Failure(error: String) extends Result[Nothing]
+
+// Case class for data
+case class User(
+  id: String,
+  name: String,
+  email: Option[String] = None,
+  age: Option[Int] = None
+)
+
+// Pattern matching
+def handleResult[A](result: Result[A]): String = result match {
+  case Success(value) => s"Got value: $value"
+  case Failure(error) => s"Error: $error"
+}
+
+// Option handling
+def getUserEmail(user: User): String = 
+  user.email.getOrElse("no-email@example.com")
+```
+
+## Functional Programming
+
+- Prefer immutability
+- Use pure functions
+- Avoid side effects
+- Use for-comprehensions for monadic operations
+
+Example:
+```scala
+// ✅ GOOD: Immutable, pure functions
+class DataProcessor(threshold: Double) {
+  def process(data: List[Int]): List[Int] = 
+    data.filter(_ > threshold)
+  
+  def transform(data: List[Int]): List[String] =
+    data.map(x => s"Value: $x")
+  
+  def pipeline(data: List[Int]): List[String] = for {
+    filtered <- Some(process(data))
+    transformed <- Some(transform(filtered))
+  } yield transformed
+}
+
+// ❌ BAD: Mutable, impure
+class DataProcessor(var threshold: Double) {
+  var results: List[Int] = List.empty  // Mutable state!
+  
+  def process(data: List[Int]): Unit = {  // Side effect!
+    results = data.filter(_ > threshold)
+    println(results)  // More side effects!
+  }
+}
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows:
+
+1. **Testing** (`scala-test.yml`):
+   - Test on ubuntu-latest
+   - Scala versions: 3.3.x
+   - sbt test with coverage
+
+2. **Linting** (`scala-lint.yml`):
+   - scalafmtCheckAll
+   - scalafixAll --check
+   - wartremoverCheck
+
+3. **Build** (`scala-build.yml`):
+   - sbt compile
+   - sbt package
+   - Verify artifacts
+
+## Publishing
+
+### To Maven Central
+
+```bash
+# 1. Configure credentials in ~/.sbt/1.0/sonatype.sbt
+# 2. Update version
+# 3. Run quality checks
+sbt clean scalafmtCheckAll test
+
+# 4. Publish
+sbt publishSigned
+sbt sonatypeBundleRelease
+```
+
+<!-- SCALA:END -->