round 2

Author: pelikhan

packages/cli/src/run.ts

@@ -733,10 +733,6 @@ export async function runScriptInternal(
     stats.log()
     if (outTraceFilename) logVerbose(`   trace: ${outTraceFilename}`)
     if (outputFilename) logVerbose(`  output: ${outputFilename}`)
-    if (outTraceFilename)
-        logVerbose(
-            `  viewer: ${SERVER_LOCALHOST}:${SERVER_PORT}/#runid=${runId}  (to start server, run 'genaiscript serve')`
-        )
 
     if (result.status !== "success" && result.status !== "cancelled") {
         const msg =

packages/core/src/annotations.ts

@@ -52,8 +52,8 @@ const SEV_EMOJI_MAP: Record<string, string> = Object.freeze({
 /**
  * Parses annotations from TypeScript, GitHub Actions, and Azure DevOps.
  *
- * @param text - The input text containing annotations to be parsed.
- * @returns An array of unique Diagnostic objects extracted from the text.
+ * @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[] {
     if (!text) return []
@@ -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 to convert. Includes severity, message, filename, and range.
- * @returns A formatted Azure DevOps command string or debug message for "info" severity.
+ * @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.
  */
 export function convertDiagnosticToAzureDevOpsCommand(d: Diagnostic) {
     // Handle 'info' severity separately with a debug message.
@@ -151,10 +151,10 @@ export function convertDiagnosticToAzureDevOpsCommand(d: Diagnostic) {
 }
 
 /**
- * Converts annotations in text to a Markdown representation.
+ * Converts annotations in text to a Markdown representation with severity-based admonitions.
  *
- * @param text - Input text with annotations to be converted.
- * @returns Formatted string in Markdown with admonitions for severity levels.
+ * @param text Input text containing annotations to be converted.
+ * @returns Formatted Markdown string with severity levels mapped to admonitions.
  */
 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 with severity, filename, range, code, and message.
- * @param sep - Separator for CSV fields.
- * @returns CSV string with each diagnostic entry on a new line.
+ * @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.
  */
 export function diagnosticsToCSV(diagnostics: Diagnostic[], sep: string) {
     return diagnostics
@@ -39,10 +39,10 @@ export function diagnosticsToCSV(diagnostics: Diagnostic[], sep: string) {
 }
 
 /**
- * Determines the group name of a given template.
- * @param template - The template object to evaluate.
- * @returns Group name of the template, "system" if the ID starts with "system", 
- * or "unassigned" if no group is set.
+ * Determines the group name of a template.
+ * @param template - The template to evaluate, containing an ID and optional group.
+ * @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.
  */
 export function templateGroup(template: PromptScript) {
     return (
@@ -57,9 +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 identifies the presence of JS or TS files in each directory.
- * @param prj - The project containing the scripts to process.
- * @returns An array of objects, each representing a directory with its name and boolean flags for JS and TS file presence.
+ * 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.
+ * @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) {
     const folders: Record<
@@ -80,9 +80,9 @@ export function collectFolders(prj: Project) {
 
 /**
  * Retrieves a script by its ID from the project's scripts list.
- * @param prj - The project containing the scripts.
- * @param system - The system prompt instance with the script ID to find.
- * @returns The matching PromptScript or undefined if no match is found.
+ * @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.
  */
 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

@@ -32,11 +32,11 @@ export class AbortSignalCancellationToken implements CancellationToken {
 }
 
 /**
- * Converts a CancellationToken to an AbortSignal if it supports the conversion.
- * Returns undefined if the token does not have a compatible signal.
+ * Converts a CancellationToken to an AbortSignal if supported.
+ * Returns undefined if the token does not have a compatible signal property.
  *
  * @param token - The CancellationToken to convert.
- * @returns The associated AbortSignal, or undefined if unsupported.
+ * @returns The associated AbortSignal or undefined if unsupported.
  */
 export function toSignal(token: CancellationToken) {
     return (token as any)?.signal as AbortSignal

packages/core/src/chatrender.ts

@@ -25,9 +25,9 @@ export interface ChatRenderOptions extends CancellationOptions {
 }
 
 /**
- * Renders the output of a shell command based on its components.
- * @param output - Contains exit code, stdout, and stderr from the shell execution.
- * @returns A formatted string summarizing the shell output, including non-zero exit code, stdout, or stderr.
+ * Formats the output of a shell command.
+ * @param output - Object containing exit code, stdout, and stderr from shell execution.
+ * @returns A formatted string summarizing the shell output, including exit code (if non-zero), stdout, and stderr.
  */
 export function renderShellOutput(output: ShellOutput) {
     // Destructure the output object to retrieve exitCode, stdout, and stderr.
@@ -51,9 +51,10 @@ export function renderShellOutput(output: ShellOutput) {
 
 /**
  * Renders the content of a message into a formatted string.
- * @param msg - The message object, which may contain various content types (e.g., text, image, audio).
- * @param options - Configuration options for rendering, such as text language or image caching.
- * @returns A formatted string representation of the message content or undefined if content is invalid.
+ * 
+ * @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.
  */
 export async function renderMessageContent(
     msg:
@@ -107,10 +108,10 @@ export function lastAssistantReasoning(messages: ChatCompletionMessageParam[]) {
 }
 
 /**
- * Renders a list of chat messages into a markdown string.
- * @param messages - The list of chat messages to render.
- * @param options - Configuration options for filtering by roles and formatting.
- * @returns The rendered markdown string representation of the chat messages.
+ * 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.
+ * @returns A markdown string representation of the chat messages.
  */
 export async function renderMessagesToMarkdown(
     messages: ChatCompletionMessageParam[],

packages/core/src/chunkers.ts

@@ -1,6 +1,11 @@
 import { assert } from "./assert"
 
-// chunk string into chunks of size n
+/**
+* // 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.
+*/
 export function chunkString(s: string, n: number = 2 << 14) {
     if (!s?.length) return []
     if (s.length <= n) return [s]

packages/core/src/cleaners.ts

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

packages/core/src/config.ts

@@ -165,9 +165,9 @@ export async function readConfig(
 }
 
 /**
- * Outputs environment information for model providers.
- * @param provider - The specific provider to filter by (optional).
- * @param options - Configuration options, including whether to show tokens.
+ * 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.
  */
 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 - Whether to enable or disable console colors.
+ * @param enabled - Indicates whether to enable or disable color output.
  */
 export function setConsoleColors(enabled: boolean) {
     consoleColors = !!enabled
@@ -21,8 +21,8 @@ export function setConsoleColors(enabled: boolean) {
  */
 /**
  * Wraps a message with ANSI escape codes for the specified color.
- * @param n - Color code or string to apply.
- * @param message - Text to be wrapped with color codes.
+ * @param n - The ANSI color code or string to apply.
+ * @param message - The text to wrap with color codes.
  */
 export function wrapColor(n: number | string, message: string) {
     if (consoleColors) return `\x1B[${n}m${message}\x1B[0m`

packages/core/src/copy.ts

@@ -24,14 +24,15 @@ function promptPath(id: string, options?: { javascript?: boolean }) {
 
 /**
  * Copies a prompt script to a new location.
- * Can optionally fork the script if needed, ensuring that the new filename is unique.
+ * Optionally forks the script, ensuring the new filename is unique if needed.
  *
- * @param t - The prompt script object
- * @param options - Configuration options for the copy
- * @param options.fork - Indicates if the script should be forked
- * @param options.name - Optional new name for the copied script
- * @returns The file path of the copied script
- * @throws If the file already exists in the target location
+ * @param t - The prompt script object containing the source code.
+ * @param options - Configuration options for the copy operation.
+ * @param options.fork - Whether to fork the script by appending a unique suffix.
+ * @param options.name - Optional new name for the copied script.
+ * @param options.javascript - Whether to use the JavaScript file extension.
+ * @returns The file path of the copied script.
+ * @throws If the file already exists in the target location.
  */
 export async function copyPrompt(
     t: PromptScript,