round 3

Author: pelikhan

packages/core/src/annotations.ts

@@ -52,7 +52,7 @@ const SEV_EMOJI_MAP: Record<string, string> = Object.freeze({
 /**
  * Parses annotations from TypeScript, GitHub Actions, and Azure DevOps.
  *
- * @param text - Input text containing annotations to parse.
+ * @param text Input text containing annotations to parse.
  * @returns Array of unique Diagnostic objects extracted from the input text.
  */
 export function parseAnnotations(text: string): Diagnostic[] {
@@ -139,8 +139,8 @@ export function convertDiagnosticToGitHubActionCommand(d: Diagnostic) {
 /**
  * Converts a Diagnostic object to an Azure DevOps log issue command string.
  *
- * @param d - The Diagnostic object containing severity, message, filename, and range.
- * @returns A formatted Azure DevOps command string for warnings and errors, or a debug message for info severity.
+ * @param d - Diagnostic object containing severity, message, filename, and range.
+ * @returns Formatted Azure DevOps command string for warnings and errors, or a debug message for info severity.
  */
 export function convertDiagnosticToAzureDevOpsCommand(d: Diagnostic) {
     // Handle 'info' severity separately with a debug message.
@@ -153,8 +153,8 @@ export function convertDiagnosticToAzureDevOpsCommand(d: Diagnostic) {
 /**
  * Converts annotations in text to a Markdown representation with severity-based admonitions.
  *
- * @param text Input text containing annotations to be converted.
- * @returns Formatted Markdown string with severity levels mapped to admonitions.
+ * @param text Input text containing annotations to convert.
+ * @returns Formatted Markdown string with severity levels mapped to admonitions, including file and line references.
  */
 export function convertAnnotationsToMarkdown(text: string): string {
     // Maps severity levels to Markdown admonition types.

packages/core/src/ast.ts

@@ -18,9 +18,9 @@ export interface FileReference {
 
 /**
  * Converts diagnostic data into a CSV-formatted string.
- * @param diagnostics - Array of diagnostic objects containing severity, filename, range, code, and message.
- * @param sep - String used as the separator for CSV fields.
- * @returns CSV string with each diagnostic entry on a separate line.
+ * @param diagnostics - Array of diagnostic objects with severity, filename, range, code, and message.
+ * @param sep - Separator string for CSV fields.
+ * @returns CSV string with each diagnostic entry on a new line.
  */
 export function diagnosticsToCSV(diagnostics: Diagnostic[], sep: string) {
     return diagnostics
@@ -40,9 +40,9 @@ export function diagnosticsToCSV(diagnostics: Diagnostic[], sep: string) {
 
 /**
  * Determines the group name of a template.
- * @param template - The template to evaluate, containing an ID and optional group.
+ * @param template - The template object to evaluate, containing an ID and an optional group property.
  * @returns The group name of the template. Returns "system" if the ID starts with "system", 
- * the existing group if set, or "unassigned" if no group is determined.
+ * the group property if set, or "unassigned" if no group is determined.
  */
 export function templateGroup(template: PromptScript) {
     return (
@@ -57,8 +57,9 @@ export const eolPosition = 0x3fffffff // End of line position, a large constant
 export const eofPosition: CharPosition = [0x3fffffff, 0] // End of file position, a tuple with a large constant
 
 /**
- * Organizes templates by directory and determines the presence of JavaScript or TypeScript files in each directory.
- * @param prj - The project containing the scripts to analyze.
+ * Organizes templates by directory and identifies the presence of JavaScript or TypeScript files in each directory.
+ * Filters out templates without filenames or matching the PROMPTY_REGEX.
+ * @param prj - The project containing the scripts to process.
  * @returns An array of objects, each representing a directory with its name and flags indicating the presence of JavaScript and TypeScript files.
  */
 export function collectFolders(prj: Project) {
@@ -79,10 +80,10 @@ export function collectFolders(prj: Project) {
 }
 
 /**
- * Retrieves a script by its ID from the project's scripts list.
+ * Finds a script in the project's scripts list by matching its ID with the system prompt instance.
  * @param prj - The project containing the scripts to search.
- * @param system - The system prompt instance containing the script ID to match.
- * @returns The matching script or undefined if no match is found.
+ * @param system - The system prompt instance with the script ID to match.
+ * @returns The matching script if found, otherwise undefined.
  */
 export function resolveScript(prj: Project, system: SystemPromptInstance) {
     return prj?.scripts?.find((t) => t.id == system.id) // Find and return the template with the matching ID

packages/core/src/cancellation.ts

@@ -33,7 +33,7 @@ export class AbortSignalCancellationToken implements CancellationToken {
 
 /**
  * Converts a CancellationToken to an AbortSignal if supported.
- * Returns undefined if the token does not have a compatible signal property.
+ * If the token lacks a compatible signal property, returns undefined.
  *
  * @param token - The CancellationToken to convert.
  * @returns The associated AbortSignal or undefined if unsupported.

packages/core/src/chatrender.ts

@@ -52,9 +52,11 @@ export function renderShellOutput(output: ShellOutput) {
 /**
  * Renders the content of a message into a formatted string.
  * 
- * @param msg - The message object containing content, which may include text, images, audio, or other types.
- * @param options - Configuration options for rendering, including text formatting, image caching, and language.
- * @returns A formatted string representation of the message content, or undefined if the content is invalid.
+ * @param msg - The message object containing content, which may include text, images, audio, or other types. 
+ *              Supports both string and array-based content.
+ * @param options - Configuration options for rendering, including text formatting, image caching, and language. 
+ *                  Includes optional functions for caching images.
+ * @returns A formatted string representation of the message content, or undefined if the content is invalid or unsupported.
  */
 export async function renderMessageContent(
     msg:
@@ -109,8 +111,9 @@ export function lastAssistantReasoning(messages: ChatCompletionMessageParam[]) {
 
 /**
  * Renders a list of chat messages into a formatted markdown string.
- * @param messages - The list of chat messages to process and render.
- * @param options - Configuration options for filtering messages by roles, formatting, and tool inclusion.
+ * 
+ * @param messages - The list of chat messages to render.
+ * @param options - Configuration options for filtering messages by role, formatting language, cancellation, and tool inclusion.
  * @returns A markdown string representation of the chat messages.
  */
 export async function renderMessagesToMarkdown(

packages/core/src/chunkers.ts

@@ -1,10 +1,10 @@
 import { assert } from "./assert"
 
 /**
-* // Splits a string into chunks of specified size.
-* // Parameters:
-* // - s: The input string to be chunked.
-* // - n: The maximum size of each chunk. Defaults to 2 << 14.
+* Splits a string into chunks of specified size.
+* Parameters:
+* - s: Input string to be split into chunks.
+* - n: Maximum size of each chunk. Defaults to 2 << 14.
 */
 export function chunkString(s: string, n: number = 2 << 14) {
     if (!s?.length) return []

packages/core/src/cleaners.ts

@@ -83,8 +83,8 @@ export function unmarkdown(text: string) {
 }
 
 /**
- * Collapses sequences of three or more consecutive newlines into two newlines.
- * @param res The input string to be processed.
+ * Collapses sequences of three or more consecutive newlines into two consecutive newlines.
+ * @param res Input string to process.
  */
 export function collapseNewlines(res: string): string {
     return res?.replace(/(\r?\n){3,}/g, "\n\n")

packages/core/src/config.ts

@@ -166,8 +166,12 @@ export async function readConfig(
 
 /**
  * Resolves and outputs environment information for language model providers.
- * @param provider - Specific provider to filter by (optional).
- * @param options - Configuration options, including whether to show tokens, errors, models, or hide hidden providers.
+ * @param provider - Filters by specific provider (optional).
+ * @param options - Configuration options: 
+ *   - token: Whether to include tokens.
+ *   - error: Whether to include errors.
+ *   - models: Whether to list models.
+ *   - hide: Whether to exclude hidden providers.
  */
 export async function resolveLanguageModelConfigurations(
     provider: string,

packages/core/src/consolecolor.ts

@@ -6,7 +6,7 @@ export let consoleColors = !!stdout.isTTY
 
 /**
  * Enables or disables console color output.
- * @param enabled - Indicates whether to enable or disable color output.
+ * @param enabled - Whether to enable or disable color output.
  */
 export function setConsoleColors(enabled: boolean) {
     consoleColors = !!enabled
@@ -22,7 +22,7 @@ export function setConsoleColors(enabled: boolean) {
 /**
  * Wraps a message with ANSI escape codes for the specified color.
  * @param n - The ANSI color code or string to apply.
- * @param message - The text to wrap with color codes.
+ * @param message - The text to wrap with ANSI escape codes.
  */
 export function wrapColor(n: number | string, message: string) {
     if (consoleColors) return `\x1B[${n}m${message}\x1B[0m`
@@ -33,10 +33,10 @@ export function wrapColor(n: number | string, message: string) {
 /**
  * Wraps text with RGB ANSI color codes for foreground or background.
  * Converts an RGB integer to its red, green, and blue components and applies the corresponding ANSI escape codes.
- * Does nothing if color output is disabled.
- * @param rgb - The RGB color as a single integer
- * @param text - The text to which the color will be applied
- * @param background - Specifies if the color is for the background
+ * Returns the original text if color output is disabled.
+ * @param rgb - RGB color as a single integer.
+ * @param text - Text to apply the color to.
+ * @param background - Whether the color is for the background.
  */
 
 export function wrapRgbColor(

packages/core/src/crypto.ts

@@ -28,8 +28,8 @@ async function digest(algorithm: string, data: Uint8Array) {
 /**
  * Generates a random hexadecimal string of the specified size.
  *
- * @param size - The number of random bytes to generate, which will be converted to a hexadecimal string.
- * @returns A hexadecimal string representation of the generated random bytes.
+ * @param size - Number of random bytes to generate, converted to a hexadecimal string.
+ * @returns Hexadecimal string representation of the generated random bytes.
  */
 export function randomHex(size: number) {
     // Create a new Uint8Array with the specified size to hold random bytes
@@ -121,9 +121,9 @@ export async function hash(value: any, options?: HashOptions) {
 /**
  * Computes the hash of a file using a streaming approach.
  *
- * @param filePath - Path to the file for which the hash is calculated.
- * @param algorithm - Hashing algorithm to use, defaults to "sha-256".
- * @returns A promise resolving to the file's hash in hexadecimal format.
+ * @param filePath - The path to the file to hash.
+ * @param algorithm - The hashing algorithm to use, defaults to "sha-256".
+ * @returns A promise that resolves to the file's hash in hexadecimal format.
  */
 export async function hashFile(
     filePath: string,

packages/core/src/csv.ts

@@ -14,7 +14,7 @@ import { filenameOrFileToContent } from "./unwrappers"
  * @param text - The CSV string or file to parse.
  * @param options - Optional configuration for parsing.
  * @param options.delimiter - The delimiter used in the CSV, defaults to a comma.
- * @param options.headers - Column headers for the CSV, as an array or single value.
+ * @param options.headers - Column headers for the CSV, as an array or single value. If not provided, headers are inferred from the first line.
  * @param options.repair - Whether to repair common escape errors, defaults to false.
  * @returns An array of objects representing the parsed CSV data.
  */
@@ -55,13 +55,13 @@ export function CSVParse(
 /**
  * Attempts to parse a CSV string into an array of objects, handling errors gracefully.
  *
- * @param text - The CSV string to parse.
+ * @param text - The CSV string to parse. Returns an empty array if the input is empty.
  * @param options - Optional configuration for parsing and error handling.
- * @param options.delimiter - Delimiter to separate values, defaults to comma.
- * @param options.headers - Array of column headers for the parsed data.
- * @param options.repair - Flag to enable basic error correction in the input data.
- * @param options.trace - Optional trace function for logging errors during parsing.
- * @returns An array of objects representing the parsed CSV data, or undefined on error.
+ * @param options.delimiter - The delimiter used to separate values, defaults to a comma.
+ * @param options.headers - Column headers for the parsed data, as an array or single value.
+ * @param options.repair - Enables basic error correction in the input data.
+ * @param options.trace - Trace function for logging errors during parsing.
+ * @returns An array of objects representing the parsed CSV data, or undefined if an error occurs.
  */
 export function CSVTryParse(
     text: string,
@@ -87,7 +87,7 @@ export function CSVTryParse(
  * Converts an array of objects into a CSV string.
  *
  * @param csv - Array of objects to convert to CSV format. Returns an empty string if the input is null or undefined.
- * @param options - Optional configuration for CSV stringification, including headers and delimiter settings.
+ * @param options - Configuration for CSV stringification, including headers and delimiter settings.
  * @returns A CSV formatted string representation of the input data.
  */
 export function CSVStringify(csv: object[], options?: CSVStringifyOptions) {
@@ -97,12 +97,12 @@ export function CSVStringify(csv: object[], options?: CSVStringifyOptions) {
 }
 
 /**
- * Converts an array of objects into a Markdown table format.
+ * Converts an array of objects into a Markdown table.
  *
- * @param csv - The array of objects representing CSV data.
- * @param options - Options for formatting the table.
- * @param options.headers - Array of headers for the table columns.
- * @returns A string representing the CSV data in Markdown table format.
+ * @param csv - Array of objects representing the data to convert.
+ * @param options - Configuration options for the table.
+ * @param options.headers - Headers for the table columns. If not provided, keys from the first object are used.
+ * @returns A Markdown table as a string.
  */
 export function dataToMarkdownTable(
     csv: object[],
@@ -154,9 +154,9 @@ export function objectToMarkdownTableRow(
 /**
  * Splits an array of objects into chunks of a specified size.
  * 
- * @param rows - The array of objects to split into chunks.
- * @param size - The size of each chunk.
- * @returns An array of chunk objects with starting index and rows.
+ * @param rows - Array of objects to be divided into chunks.
+ * @param size - Number of objects per chunk. Must be at least 1.
+ * @returns Array of chunk objects, each containing a starting index and rows.
  */
 export function CSVChunk(
     rows: object[],