From 489b2594df296d94bab31e86fad899ca77d75125 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Mon, 23 Jun 2025 02:20:27 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`feature?=
 =?UTF-8?q?/expand-log-browser`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @miklschmidt.

* https://github.com/Rat-OS/RatOS-configurator/pull/96#issuecomment-2994700989

The following files were modified:

* `src/app/logs/page.tsx`
* `src/server/routers/logs.ts`
---
 src/app/logs/page.tsx      |  5 +++++
 src/server/routers/logs.ts | 38 +++++++++++++++++++++++++++++++++-----
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/src/app/logs/page.tsx b/src/app/logs/page.tsx
index e9464ac18..61b0449db 100644
--- a/src/app/logs/page.tsx
+++ b/src/app/logs/page.tsx
@@ -1,6 +1,11 @@
 import { LogsViewer } from '@/app/logs/_components/logs-viewer';
 import { LogsErrorBoundary } from '@/app/logs/_components/logs-error-boundary';
 
+/**
+ * Renders the logs viewer page with error boundary protection.
+ *
+ * Displays the `LogsViewer` component wrapped in a `LogsErrorBoundary` to handle and display errors that may occur during log viewing.
+ */
 export default function LogsPage() {
 	return (
 		<LogsErrorBoundary>
diff --git a/src/server/routers/logs.ts b/src/server/routers/logs.ts
index d235a5dc5..bf3fbe632 100644
--- a/src/server/routers/logs.ts
+++ b/src/server/routers/logs.ts
@@ -75,7 +75,13 @@ const LOG_LEVEL_MAP: Record<string, number> = {
 	fatal: 60,
 };
 
-// Parse log file and extract all entries, adding default source for entries without one
+/**
+ * Reads and parses a log file, returning all log entries with a default source of "server" assigned to entries missing a source.
+ *
+ * @param logPath - Path to the log file to parse
+ * @returns An array of log entries sorted by ascending timestamp
+ * @throws If the log file cannot be read or parsed
+ */
 export async function parseLogFile(logPath: string): Promise<LogEntry[]> {
 	try {
 		const result = await readObjects(logPath, LogEntrySchema);
@@ -172,12 +178,24 @@ export function generateSummary(entries: LogEntry[], logFileSize: number, logFil
 	return summary;
 }
 
-// Filter entries by severity level
+/**
+ * Returns log entries with a severity level greater than or equal to the specified minimum.
+ *
+ * @param entries - The array of log entries to filter
+ * @param minLevel - The minimum severity level to include
+ * @returns An array of log entries meeting the minimum severity requirement
+ */
 export function filterBySeverity(entries: LogEntry[], minLevel: number): LogEntry[] {
 	return entries.filter((entry) => entry.level >= minLevel);
 }
 
-// Filter entries by context (supports single value or array)
+/**
+ * Filters log entries by context, supporting a single context value or an array of contexts.
+ *
+ * @param entries - The array of log entries to filter
+ * @param context - A context string or array of context strings to match
+ * @returns An array of log entries whose context matches the specified value(s)
+ */
 export function filterByContext(entries: LogEntry[], context: string | string[]): LogEntry[] {
 	if (Array.isArray(context)) {
 		return entries.filter((entry) => entry.context && context.includes(entry.context));
@@ -185,7 +203,13 @@ export function filterByContext(entries: LogEntry[], context: string | string[])
 	return entries.filter((entry) => entry.context === context);
 }
 
-// Filter entries by source (supports single value or array)
+/**
+ * Filters log entries by their source field.
+ *
+ * @param entries - The array of log entries to filter
+ * @param source - A source string or array of source strings to match
+ * @returns An array of log entries whose source matches the specified value(s)
+ */
 export function filterBySource(entries: LogEntry[], source: string | string[]): LogEntry[] {
 	if (Array.isArray(source)) {
 		return entries.filter((entry) => entry.source && source.includes(entry.source));
@@ -193,7 +217,11 @@ export function filterBySource(entries: LogEntry[], source: string | string[]):
 	return entries.filter((entry) => entry.source === source);
 }
 
-// Get log file path - now uses the main RatOS log file
+/**
+ * Retrieves the main RatOS log file path from environment variables.
+ *
+ * @returns The absolute path to the log file as specified in the environment.
+ */
 function getLogFilePath(): string {
 	const environment = serverSchema.parse(process.env);
 	return environment.LOG_FILE;