adding auto-generated comments

Author: pelikhan

packages/core/src/agent.ts

@@ -11,6 +11,21 @@ import { prettifyMarkdown } from "./markdown"
 import { MarkdownTrace, TraceOptions } from "./trace"
 import { logVerbose } from "./util"
 
+/**
+ * Queries the memory for contextual information relevant to the given query.
+ * 
+ * The function retrieves memories associated with the user state and processes them 
+ * to return concise answers. If no relevant information is found, it returns 
+ * a predefined token indicating no answer is available. The querying process is done 
+ * using a language model, ensuring that only memory content is utilized to formulate the response.
+ *
+ * @param ctx - The context object for the chat generation process.
+ * @param query - The user's query to find relevant information in memory.
+ * @param options - Options including user state and tracing details for the memory query.
+ * 
+ * @returns A string containing the memory answer or undefined if the query is empty 
+ *          or no memories are found.
+ */
 export async function agentQueryMemory(
     ctx: ChatGenerationContext,
     query: string,
@@ -48,6 +63,18 @@ export async function agentQueryMemory(
     return memoryAnswer
 }
 
+/**
+ * Adds a memory entry to the agent's memory cache.
+ * 
+ * This function stores a specified answer related to a query made by the agent.
+ * The memory is cached using a unique key combining the agent and query. 
+ * Additionally, it provides tracing details for the stored memory.
+ * 
+ * @param agent - The identifier for the agent.
+ * @param query - The query for which the memory is being added.
+ * @param text - The response text to be stored in memory.
+ * @param options - Additional options, including user state and trace options.
+ */
 export async function agentAddMemory(
     agent: string,
     query: string,
@@ -92,6 +119,16 @@ async function loadMemories(options: Pick<GenerationOptions, "userState">) {
     return memories
 }
 
+/**
+ * Traces and logs the agent's memory details.
+ *
+ * This function retrieves stored memories for the agent based on the provided options. 
+ * It formats and displays each memory entry in reverse order, including the agent's name, 
+ * the query, and the corresponding answer. The trace context is used to encapsulate 
+ * these details and provide structured logging of the memory.
+ *
+ * @param options - The context options for the current generation, which include user state and tracing options.
+ */
 export async function traceAgentMemory(
     options: Pick<GenerationOptions, "userState"> & Required<TraceOptions>
 ) {

packages/core/src/annotations.ts

@@ -86,10 +86,30 @@ export function parseAnnotations(text: string): Diagnostic[] {
     return Array.from(annotations.values()) // Convert the set to an array
 }
 
+/**
+ * Removes annotations from the input text.
+ *
+ * This function utilizes regular expressions defined for TypeScript, GitHub Actions, and Azure DevOps annotations
+ * to replace occurrences of annotations with an empty string, effectively erasing them from the provided text.
+ *
+ * @param text - The input text containing annotations to be erased.
+ * @returns The input text with all annotations removed.
+ */
 export function eraseAnnotations(text: string) {
     return ANNOTATIONS_RX.reduce((t, rx) => t.replace(rx, ""), text)
 }
 
+/**
+ * Transforms text annotations into diagnostic items.
+ * 
+ * This function utilizes annotated regex patterns to identify and extract
+ * diagnostic information from the input text. It constructs `Diagnostic`
+ * objects from matched groups, which are then converted into a string
+ * representation.
+ * 
+ * @param text - The input text containing annotations to be converted.
+ * @returns A string of formatted diagnostic items derived from the annotations.
+ */
 export function convertAnnotationsToItems(text: string) {
     return ANNOTATIONS_RX.reduce(
         (t, rx) =>
@@ -112,6 +132,15 @@ export function convertAnnotationsToItems(text: string) {
     )
 }
 
+/**
+ * Converts a `Diagnostic` object into a formatted string representation.
+ *
+ * The formatted string includes an emoji corresponding to the severity level,
+ * the diagnostic message, and the filename with an optional line number link.
+ *
+ * @param d - The `Diagnostic` object to convert.
+ * @returns A formatted string representing the annotation.
+ */
 export function convertAnnotationToItem(d: Diagnostic) {
     const { severity, message, filename, code, range } = d
     const line = range?.[0]?.[0]

packages/core/src/assert.ts

@@ -1,3 +1,16 @@
+/**
+* """
+* Asserts that a given condition is true. If the condition is false, logs an error message and throws an exception. Optionally supports additional debug data for logging.
+* 
+* Parameters:
+* - cond: A boolean condition to evaluate.
+* - msg: An optional message to display if the assertion fails.
+* - debugData: Optional extra data for debugging output when the assertion fails.
+* 
+* Throws:
+* - Error with the provided message if the condition is false.
+* """
+*/
 export function assert(
     cond: boolean,
     msg = "Assertion failed",

packages/core/src/ast.ts

@@ -94,6 +94,17 @@ export interface ScriptFilterOptions {
     unlisted?: boolean
 }
 
+/**
+ * Filters an array of scripts based on specified options.
+ * 
+ * This function allows the application of multiple filters to the given scripts
+ * such as filtering by IDs, groups, and flags for test, redteam, and unlisted statuses.
+ * 
+ * @param scripts - The array of scripts to be filtered.
+ * @param options - The filtering options that determine which scripts to include in the result.
+ * 
+ * @returns An array of scripts that match the specified filtering criteria.
+ */
 export function filterScripts(
     scripts: PromptScript[],
     options: ScriptFilterOptions

packages/core/src/astgrep.ts

@@ -8,6 +8,19 @@ import { host } from "./host"
 import { uniq } from "es-toolkit"
 import { readText, writeText } from "./fs"
 
+/**
+ * Searches for files matching a specified glob pattern and applies a matcher to find nodes within those files.
+ * 
+ * @param lang - The programming language to use for parsing files.
+ * @param glob - A pattern or array of patterns to match files.
+ * @param matcher - A string or matcher object used to identify nodes in the files.
+ * @param options - Options to configure the search process, including cancellation options.
+ * 
+ * @returns An object containing the number of files scanned, matched nodes, a replace function to modify nodes, 
+ *          and a commitEdits function to apply changes to the files.
+ * 
+ * @throws Error if glob or matcher is not provided.
+ */
 export async function astGrepFindFiles(
     lang: SgLang,
     glob: ElementOrArray<string>,
@@ -105,6 +118,14 @@ export async function astGrepFindFiles(
     return { files: scanned, matches, replace, commitEdits }
 }
 
+/**
+ * Writes edits to the roots of the provided nodes. For each unique root,
+ * it checks if the current content differs from the updated content. If they 
+ * are different, it writes the updated content to the corresponding file.
+ * 
+ * @param nodes - An array of nodes whose edits need to be written.
+ * @param options - Optional settings that may include a cancellation token.
+ */
 export async function astGrepWriteRootEdits(
     nodes: SgNode[],
     options?: CancellationOptions
@@ -127,6 +148,20 @@ export async function astGrepWriteRootEdits(
     }
 }
 
+/**
+ * Parses the content of a given workspace file and resolves its language.
+ *
+ * This function checks for binary encoding, retrieves the file content, 
+ * and utilizes the AST-Grep library to parse the content based on the 
+ * specified or inferred language. It supports cancellation tokens to 
+ * allow for interruption of long-running processes.
+ *
+ * @param file The workspace file to be parsed.
+ * @param options Optional parameters including language specification 
+ *                and cancellation options.
+ * @returns The root AST node of the parsed file content, or undefined 
+ *          if the file is binary or if the language cannot be resolved.
+ */
 export async function astGrepParse(
     file: WorkspaceFile,
     options?: { lang?: SgLang } & CancellationOptions

packages/core/src/azurecontentsafety.ts

@@ -239,6 +239,12 @@ class AzureContentSafetyClient implements ContentSafety {
     }
 }
 
+/**
+ * Checks if the Azure Content Safety client is configured correctly.
+ * This is determined by the presence of the necessary endpoint environment variable.
+ * 
+ * @returns A boolean indicating whether the Azure Content Safety client is configured.
+ */
 export function isAzureContentSafetyClientConfigured() {
     const endpoint = trimTrailingSlash(
         process.env.AZURE_CONTENT_SAFETY_ENDPOINT ||
@@ -247,6 +253,12 @@ export function isAzureContentSafetyClientConfigured() {
     return !!endpoint
 }
 
+/**
+ * Creates an instance of the Azure Content Safety client.
+ *
+ * @param options Configuration options including cancellation options and tracing options.
+ * @returns An object implementing the ContentSafety interface with methods to detect harmful content and prompt injection.
+ */
 export function createAzureContentSafetyClient(
     options: CancellationOptions &
         TraceOptions & {

packages/core/src/azuredevops.ts

@@ -78,6 +78,22 @@ async function findPullRequest(info: AzureDevOpsEnv) {
     return pr
 }
 
+/**
+ * Updates the description of an existing pull request in Azure DevOps.
+ * 
+ * This function retrieves the pull request associated with the provided 
+ * Azure DevOps environment information, formats the given text, and appends
+ * it to the existing description. A footer generated by the script is also added.
+ * 
+ * If the pull request is found, the function sends a PATCH request to update
+ * the description. Error logging is performed if the update fails.
+ * 
+ * @param script The script object used to generate the footer for the description.
+ * @param info The Azure DevOps environment information containing access and 
+ *              repository details.
+ * @param text The new text to be added to the pull request description.
+ * @param commentTag A tag used for merging the description.
+ */
 export async function azureDevOpsUpdatePullRequestDescription(
     script: PromptScript,
     info: AzureDevOpsEnv,
@@ -116,6 +132,18 @@ export async function azureDevOpsUpdatePullRequestDescription(
     else logVerbose(`pull request updated`)
 }
 
+/**
+ * Creates a comment on an Azure DevOps pull request.
+ * 
+ * This function retrieves the pull request ID based on the provided environment information,
+ * assembles the comment body, and submits it as a new comment thread. If a commentTag is provided,
+ * it checks for existing active threads with the same tag and closes them before creating a new comment.
+ * 
+ * @param script - The script that initiated the call.
+ * @param info - Environment information needed for Azure DevOps API calls.
+ * @param body - The content of the comment to be added.
+ * @param commentTag - An optional tag to identify and close old comment threads.
+ */
 export async function azureDevOpsCreateIssueComment(
     script: PromptScript,
     info: AzureDevOpsEnv,

packages/core/src/azuretoken.ts

@@ -169,6 +169,14 @@ class AzureTokenResolverImpl implements AzureTokenResolver {
     }
 }
 
+/**
+ * Creates an instance of AzureTokenResolver.
+ *
+ * @param name - The name identifier for the token resolver.
+ * @param envName - The environment name from which to read the secret.
+ * @param scopes - An array of scopes required for the Azure authentication token.
+ * @returns An instance of AzureTokenResolver, which is responsible for obtaining and managing Azure authentication tokens.
+ */
 export function createAzureTokenResolver(
     name: string,
     envName: string,

packages/core/src/bufferlike.ts

@@ -2,6 +2,18 @@ import { resolveFileBytes } from "./file"
 import { TraceOptions } from "./trace"
 import { fileTypeFromBuffer } from "./filetype"
 
+/**
+ * Resolves a buffer-like object into a Buffer.
+ * Supports various input types including string URLs, Blob, ReadableStream,
+ * ArrayBuffer, Uint8Array, and objects containing a filename.
+ * 
+ * @param bufferLike - The buffer-like object to resolve.
+ * @param options - Optional tracing options for resolution.
+ * 
+ * @returns A Promise that resolves to a Buffer.
+ * 
+ * @throws Error if the provided buffer-like object is unsupported.
+ */
 export async function resolveBufferLike(
     bufferLike: BufferLike,
     options?: TraceOptions
@@ -28,6 +40,14 @@ export async function resolveBufferLike(
     throw new Error("Unsupported buffer-like object")
 }
 
+/**
+ * Converts a Buffer or Uint8Array to a Blob, optionally specifying the MIME type.
+ * The MIME type is inferred from the buffer if not provided.
+ *
+ * @param buffer - The data to be converted.
+ * @param mime - Optional MIME type for the Blob. If not provided, detected from the buffer.
+ * @returns A Blob containing the data from the buffer.
+ */
 export async function BufferToBlob(buffer: Buffer | Uint8Array, mime?: string) {
     const type = await fileTypeFromBuffer(buffer)
     return new Blob([buffer], {