@hivehub/rulebook 1.2.0

package/templates/languages/SCALA.md

@@ -0,0 +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 -->