feat: add math utility functions

[CristianAmbrosini]

Summary

Add math_utils.py with common math helpers: fibonacci, is_prime, gcd, lcm, clamp.

Purpose

Test PR to validate Gessie telemetry events with event_timestamp and source.service fix.

[sonar-review-dev18]

Summary

This PR adds a new math_utils.py module with five utility functions: fibonacci sequence generation, prime checking, GCD/LCM computation, and value clamping. All functions include type hints. The actual code changes are minimal—this is primarily a test PR for validating Gessie telemetry event logging with event_timestamp and source.service fields.

What reviewers should know

What to focus on: The math functions are straightforward implementations and aren't the main point. The real validation target is whether the telemetry instrumentation is capturing the right metadata correctly.

Non-obvious details:

• GCD uses the Euclidean algorithm; LCM is computed via the GCD relationship
• Fibonacci returns an empty list for n ≤ 0, and [0] for n=1
• Functions lack individual docstrings (only module-level docstring present)
• No test file is included—verify if telemetry tests validate these functions or if they're tested separately

Watch for:

• Telemetry payload structure in event logs (check event_timestamp format and source.service values match expectations)
• Whether these utility functions will actually be imported/used or if they exist purely for the telemetry test scenario

---

• Generate Walkthrough
• Generate Diagram

🗣️ Give feedback

[sonarqube-cloud-dev18]

SonarQube reviewer guide

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

[sonar-review-dev18]

One real bug in lcm and missing docstrings on all public functions (required by org convention). The bug can cause a ZeroDivisionError at runtime; the docstring gaps are a hard guideline requirement.

SonarQube Cloud status: The quality gate is failing due to 0% test coverage on new code (25/25 lines). See the SonarQube Cloud reviewer guide above for details.

🗣️ Give feedback

[sonar-review-dev18]

Bug: lcm(0, 0) raises ZeroDivisionError. gcd(0, 0) returns 0 (the loop exits immediately because b is falsy), making the division crash.

Also, even for non-zero inputs, multiplying first (a * b) and dividing after is safe in Python due to arbitrary-precision integers, but the conventional approach divides first to keep intermediate values smaller.

Suggested change

	if a == 0 or b == 0:
	return 0
	return abs(a) // gcd(a, b) * abs(b)

• Mark as noise

[sonar-review-dev18]

Missing docstring: All public functions must have a docstring describing what the function does, its parameters, and its return value (org guideline).

Suggested change

	def fibonacci(n: int) -> list[int]:
	def fibonacci(n: int) -> list[int]:
	"""Return the first n numbers in the Fibonacci sequence.
	Args:
	n: How many numbers to generate. Returns [] for n <= 0.
	Returns:
	A list of n Fibonacci numbers starting from 0.
	"""

• Mark as noise

[sonar-review-dev18]

Missing docstring: Public function lacks a docstring (org guideline).

Suggested change

	def is_prime(n: int) -> bool:
	def is_prime(n: int) -> bool:
	"""Return True if n is a prime number, False otherwise.
	Args:
	n: The integer to test. Values less than 2 return False.
	Returns:
	True if n is prime, False otherwise.
	"""

• Mark as noise

[sonar-review-dev18]

Missing docstring: Public function lacks a docstring (org guideline).

Suggested change

	def gcd(a: int, b: int) -> int:
	"""Return the greatest common divisor of a and b using the Euclidean algorithm.
	Args:
	a: First integer.
	b: Second integer.
	Returns:
	The GCD of a and b.
	"""

• Mark as noise

[sonar-review-dev18]

Missing docstring: Public function lacks a docstring (org guideline).

Suggested change

	return a
	def lcm(a: int, b: int) -> int:
	"""Return the least common multiple of a and b.
	Args:
	a: First integer.
	b: Second integer.
	Returns:
	The LCM of a and b. Returns 0 if either argument is 0.
	"""

• Mark as noise

[sonar-review-dev18]

Missing docstring: Public function lacks a docstring (org guideline).

Suggested change

	def clamp(value: float, min_val: float, max_val: float) -> float:
	def clamp(value: float, min_val: float, max_val: float) -> float:
	"""Clamp value to the range [min_val, max_val].
	Args:
	value: The value to clamp.
	min_val: Lower bound (inclusive).
	max_val: Upper bound (inclusive).
	Returns:
	value constrained to [min_val, max_val].
	"""

• Mark as noise

[sonar-review-dev18]

Missing test coverage: The lcm function has a division-by-zero bug when both inputs are 0 (see the bug comment above). A unit test for lcm(0, 0), lcm(0, 5), and lcm(5, 0) would catch this class of regression.

• Mark as noise