round 4

Author: pelikhan

packages/core/src/annotations.ts

@@ -54,6 +54,8 @@ const SEV_EMOJI_MAP: Record<string, string> = Object.freeze({
  *
  * @param text Input text containing annotations to parse.
  * @returns Array of unique Diagnostic objects extracted from the input text.
+ * 
+ * Extracts details such as file, line, severity, code, and message from annotations.
  */
 export function parseAnnotations(text: string): Diagnostic[] {
     if (!text) return []
@@ -139,8 +141,8 @@ export function convertDiagnosticToGitHubActionCommand(d: Diagnostic) {
 /**
  * Converts a Diagnostic object to an Azure DevOps log issue command string.
  *
- * @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.
+ * @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. Includes filename and line number.
  */
 export function convertDiagnosticToAzureDevOpsCommand(d: Diagnostic) {
     // Handle 'info' severity separately with a debug message.
@@ -154,7 +156,7 @@ export function convertDiagnosticToAzureDevOpsCommand(d: Diagnostic) {
  * Converts annotations in text to a Markdown representation with severity-based admonitions.
  *
  * @param text Input text containing annotations to convert.
- * @returns Formatted Markdown string with severity levels mapped to admonitions, including file and line references.
+ * @returns Formatted Markdown string with severity levels mapped to admonitions, including file, line references, and optional codes.
  */
 export function convertAnnotationsToMarkdown(text: string): string {
     // Maps severity levels to Markdown admonition types.

packages/core/src/ast.ts

@@ -18,8 +18,8 @@ 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 string for CSV fields.
+ * @param diagnostics - Array of diagnostic objects containing severity, filename, range, code, and message.
+ * @param sep - String used to separate CSV fields.
  * @returns CSV string with each diagnostic entry on a new line.
  */
 export function diagnosticsToCSV(diagnostics: Diagnostic[], sep: string) {
@@ -58,9 +58,9 @@ export const eofPosition: CharPosition = [0x3fffffff, 0] // End of file position
 
 /**
  * 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.
+ * Filters out templates without filenames or those matching the PROMPTY_REGEX.
+ * @param prj - The project containing the scripts to process, with each script having a filename property.
+ * @returns 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<
@@ -82,7 +82,7 @@ export function collectFolders(prj: Project) {
 /**
  * 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 with the script ID to match.
+ * @param system - The system prompt instance containing the script ID to match.
  * @returns The matching script if found, otherwise undefined.
  */
 export function resolveScript(prj: Project, system: SystemPromptInstance) {

packages/core/src/cleaners.ts

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

packages/core/src/csv.ts

@@ -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 - Configuration for CSV stringification, including headers and delimiter settings.
+ * @param options - Optional 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) {

packages/core/src/file.ts

@@ -36,8 +36,12 @@ import { prettyBytes } from "./pretty"
 
 /**
  * Resolves the content of a file by decoding, fetching, or parsing it based on its type or source.
+ * 
  * @param file - The file object containing filename, content, type, and encoding.
  * @param options - Optional parameters for tracing, cancellation handling, and maximum file size.
+ *   - trace - Optional tracing object for logging operations.
+ *   - cancellationToken - Token to handle cancellation of the operation.
+ *   - maxFileSize - Maximum allowed file size for processing.
  * @returns The updated file object with resolved content or metadata.
  */
 export async function resolveFileContent(
@@ -181,7 +185,7 @@ export function toWorkspaceFile(fileOrFilename: string | WorkspaceFile) {
  * Resolves the contents of multiple files asynchronously.
  * Iterates through the provided files, resolving their content based on type or source.
  * @param files - Array of files to process and resolve content for.
- * @param options - Optional parameters for tracing, cancellation handling, and file processing.
+ * @param options - Optional parameters for tracing, cancellation handling, and maximum file size.
  */
 export async function resolveFileContents(
     files: WorkspaceFile[],
@@ -251,7 +255,7 @@ export function dataUriToBuffer(filename: string) {
 
 /**
  * Resolves and returns the file content as bytes.
- * @param filename - The file name, URL, data URI, or WorkspaceFile object to resolve.
+ * @param filename - The file name, URL, data URI, or WorkspaceFile object to resolve. If a WorkspaceFile object, it uses its encoding and content if available.
  * @param options - Optional parameters for tracing and cancellation handling.
  * @returns A Uint8Array containing the file content as bytes.
  */

packages/core/src/github.ts

@@ -148,7 +148,15 @@ export async function githubParseEnv(
     return Object.freeze(res)
 }
 
-// https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#update-a-pull-request
+/**
+* // Updates the description of a pull request on GitHub.
+* // Parameters:
+* // - script: The script instance used to generate the footer.
+* // - info: Object containing apiUrl, repository, issue, and runUrl.
+* // - text: The new description text to update.
+* // - commentTag: Tag used to identify and merge the description.
+* // Returns an object indicating whether the update was successful and the status text.
+*/
 export async function githubUpdatePullRequestDescription(
     script: PromptScript,
     info: Pick<

packages/core/src/image.ts

@@ -180,7 +180,7 @@ export async function imageTransform(
  * Encodes an image for use in Language Learning Models (LLMs).
  *
  * @param url - The source of the image, which can be a URL, Buffer, or Blob.
- * @param options - Configuration for image processing, including detail level, trace settings, and cancellation handling.
+ * @param options - Configuration for image processing, including detail level, trace settings, cancellation handling, and MIME type.
  * @returns A promise that resolves to the image encoded as a data URI.
  */
 export async function imageEncodeForLLM(

packages/core/src/promptcontext.ts

@@ -39,11 +39,11 @@ const dbg = debug("genaiscript:promptcontext")
  * Creates a prompt context for the specified project, variables, trace, options, and model.
  * 
  * @param prj The project for which the context is created.
- * @param ev Expansion variables including generator, output, debugging, and other configurations.
+ * @param ev Expansion variables including generator, output, debugging, run directory, and other configurations.
  * @param trace Markdown trace for logging and debugging.
  * @param options Generation options such as cancellation tokens, embeddings models, and content safety.
  * @param model The model identifier used for context creation.
- * @returns A context object providing methods for file operations, web retrieval, searches, execution, and other utilities.
+ * @returns A context object providing methods for file operations, web retrieval, searches, execution, container operations, and other utilities.
  */
 export async function createPromptContext(
     prj: Project,

packages/core/src/promptdom.ts

@@ -214,8 +214,9 @@ export interface FileOutputNode extends PromptNode {
 /**
  * Creates a text node with the specified value and optional context expansion options.
  * 
- * @param value - The string value for the text node, must be defined and can be awaited.
+ * @param value - The string value for the text node, must be defined.
  * @param options - Configuration for context expansion, applied if provided.
+ * @returns A text node object with the specified value and options.
  */
 export function createTextNode(
     value: Awaitable<string>,
@@ -397,7 +398,7 @@ ${trimNewlines(text)}
 /**
  * Creates a node representing an assistant message in a prompt.
  * @param value The content of the assistant message.
- * @param options Optional settings for context expansion.
+ * @param options Optional settings for context expansion. Defaults to an empty object if not provided.
  */
 export function createAssistantNode(
     value: Awaitable<string>,
@@ -421,6 +422,7 @@ export function createSystemNode(
  * @param strings - The template literal strings to include in the node.
  * @param args - The arguments to interpolate into the template.
  * @param options - Optional settings for context expansion or additional properties.
+ * @returns The created string template node.
  */
 export function createStringTemplateNode(
     strings: TemplateStringsArray,
@@ -440,8 +442,8 @@ export function createStringTemplateNode(
 /**
  * Creates an image node with the given value and optional context expansion options.
  * 
- * @param value - The image data or prompt used to create the node.
- * @param options - Context expansion options to include in the node.
+ * @param value - The image data or prompt used to create the node. Must not be undefined.
+ * @param options - Optional context expansion options to include in the node.
  * @returns The created image node.
  */
 export function createImageNode(
@@ -454,9 +456,10 @@ export function createImageNode(
 
 /**
  * Creates a schema node with a specified name, value, and optional configuration.
+ * 
  * Parameters:
- * - name: The name of the schema node.
- * - value: The schema definition or a Zod type to be converted to JSON Schema.
+ * - name: The name of the schema node. Must not be empty.
+ * - value: The schema definition or a Zod type to be converted to JSON Schema. Automatically converts Zod types if applicable.
  * - options: Optional configuration for the schema node.
  */
 export function createSchemaNode(
@@ -502,7 +505,8 @@ export function createFileMerge(fn: FileMergeHandler): PromptFileMergeNode {
 /** 
  * Creates and returns an output processor node with a specified handler function.
  * 
- * @param fn - Handler function to process prompt outputs. Must be defined.
+ * @param fn - Handler function to process prompt outputs. Must be defined. 
+ * @returns An output processor node containing the handler function.
  */
 export function createOutputProcessor(
     fn: PromptOutputProcessorHandler
@@ -514,6 +518,7 @@ export function createOutputProcessor(
 /**
  * Creates a node representing a chat participant.
  * @param participant - The chat participant to represent in the node.
+ * @returns A node object representing the chat participant.
  */
 export function createChatParticipant(
     participant: ChatParticipant
@@ -1216,10 +1221,10 @@ async function deduplicatePromptNode(trace: MarkdownTrace, root: PromptNode) {
  * Parameters:
  * - modelId: Identifier for the model.
  * - node: The prompt node to render.
- * - options: Optional configurations for model templates, tracing, and cancellation.
+ * - options: Optional configurations for model templates, tracing, cancellation, and token flexibility.
  * 
  * Returns:
- * - A rendered prompt node with associated metadata, messages, and resources.
+ * - A rendered prompt node with associated metadata, messages, resources, and disposables.
  */
 export async function renderPromptNode(
     modelId: string,

packages/core/src/promptfoo.ts

@@ -94,6 +94,15 @@ function renderPurpose(script: PromptScript): string {
  *
  * @param script - The script containing prompt details, tests, and redteam configurations.
  * @param options - Configuration options including chatInfo, embeddingsInfo, provider, output settings, CLI settings, redteam settings, models, trace options, and cancellation options.
+ *   - chatInfo: Connection info and model aliases for chat models.
+ *   - embeddingsInfo: Connection info for embedding models.
+ *   - provider: The provider identifier.
+ *   - out: Output directory or file path.
+ *   - cli: CLI-specific settings.
+ *   - redteam: Whether redteam configurations are enabled.
+ *   - models: Array of model options and aliases.
+ *   - trace: Trace options for debugging.
+ *   - cancellation options: Options for handling cancellation.
  * @returns A configuration object for PromptFoo based on the provided script and options.
  */
 export async function generatePromptFooConfiguration(