Create rule S8229: Date and time values should use appropriate temporal types instead of numeric primitives

rules/S8229/java/metadata.json

@@ -0,0 +1,28 @@
+{
+  "title": "Date and time values should use appropriate temporal types instead of numeric primitives",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant/Issue",
+    "constantCost": "10 min"
+  },
+  "tags": [
+    "java8",
+    "temporal",
+    "readability"
+  ],
+  "defaultSeverity": "Blocker",
+  "ruleSpecification": "RSPEC-8229",
+  "sqKey": "S8229",
+  "scope": "All",
+  "defaultQualityProfiles": [
+    "Sonar way"
+  ],
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "BLOCKER"
+    },
+    "attribute": "CLEAR"
+  }
+}

rules/S8229/java/rule.adoc

@@ -0,0 +1,55 @@
+This rule raises an issue when numeric primitives like `long` or `int` are used to represent temporal concepts such as timeouts, durations, delays, or timestamps.
+
+== Why is this an issue?
+
+Using numeric primitives to represent date and time concepts creates problems that make code harder to understand and maintain.
+
+When you see a method parameter like `setTimeout(long timeout)`, it's unclear what unit the timeout represents. Is it milliseconds? Seconds? Minutes? This ambiguity leads to confusion and bugs.
+
+Numeric primitives also lack type safety. You can accidentally pass a duration where a timestamp is expected, or mix up different time units without any compiler warnings.
+
+The Java 8+ `java.time` API provides purpose-built types like `Duration`, `Instant`, and `LocalDateTime` that carry semantic meaning, prevent unit confusion, and make your code self-documenting.
+
+=== What is the potential impact?
+
+Using numeric primitives for temporal values can lead to subtle bugs, especially when different parts of the code assume different time units. This can cause timeouts to be too short or too long, leading to performance issues or system failures. The lack of type safety also makes refactoring more dangerous, as the compiler cannot catch unit mismatches.
+
+== How to fix it
+
+Replace numeric primitive parameters with appropriate `java.time` types. Use `Duration` for time spans, `Instant` for timestamps, and other temporal types as needed.
+
+=== Code examples
+
+==== Noncompliant code example
+
+[source,java,diff-id=1,diff-type=noncompliant]
+----
+public void setTimeout(long timeout) { // Noncompliant
+    this.timeout = timeout;
+}
+
+public void scheduleTask(long delay) { // Noncompliant
+    // Schedule task after delay
+}
+----
+
+==== Compliant solution
+
+[source,java,diff-id=1,diff-type=compliant]
+----
+public void setTimeout(Duration timeout) {
+    this.timeout = timeout;
+}
+
+public void scheduleTask(Duration delay) {
+    // Schedule task after delay
+}
+----
+
+== Resources
+
+=== Documentation
+
+ * Duration Class Documentation - https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html[Official documentation for the Duration class]
+
+ * Instant Class Documentation - https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html[Official documentation for the Instant class]

rules/S8229/metadata.json

@@ -0,0 +1,2 @@
+{
+}