Added further documentation for connectionManager, executeCql, and normalizeCqlExecution

Author: jreyno77

src/connectionManager.ts

@@ -17,7 +17,127 @@ export interface Connection {
 }
 
 /**
- * Manages connections and their associated contexts.
+ * Manages multiple FHIR data connections and their associated contexts for CQL evaluations.
+ *
+ * The **Connection Manager** allows for managing multiple data connections, but only one connection can be active at a time.
+ * It currently supports FHIR server connections and local file system connections. It provides full CRUD capabilities and
+ * ensures that connections and contexts persist across sessions using VS Code's global state storage.
+ *
+ *
+ * **Quick Example:**
+ *
+ * - **Creating a New Connection**:
+ *   ```typescript
+ *   const connection: Connection = {
+ *     name: "Local Connection",
+ *     endpoint: "file:///Users/username/test-dir",
+ *     contexts: {
+ *       "Patient/123": {
+ *         resourceID: "123",
+ *         resourceType: "Patient",
+ *         resourceDisplay: "John Doe"
+ *       }
+ *     }
+ *   };
+ *   ConnectionManager.getManager().upsertConnection(connection);
+ *   ```
+ *
+ *
+ * - **Setting the Active Connection**:
+ *   ```typescript
+ *   ConnectionManager.getManager().setCurrentConnection("Local Connection");
+ *   ```
+ *
+ * **Key Operations:**
+ *
+ * - **Read**: Retrieve all stored connections and their associated contexts.
+ * - **Upsert**: Add or update connections and contexts.
+ * - **Delete**: Remove connections and contexts.
+ *
+ * **Further Examples:**
+ *
+ * - **Retrieving the Current Active Connection**:
+ *   ```typescript
+ *   const currentConnection = ConnectionManager.getManager().getCurrentConnection();
+ *   console.log(currentConnection);
+ *   ```
+ *
+ * - **Deleting a Connection**:
+ *   ```typescript
+ *   ConnectionManager.getManager().deleteConnection("Remote Connection");
+ *   ```
+ *
+ * **CRUD Operations:**
+ *
+ * - **Create or Update a Connection**:
+ *   Use `upsertConnection` to add a new connection or update an existing one.
+ *   ```typescript
+ *   ConnectionManager.getManager().upsertConnection(connection);
+ *   ```
+ *
+ * - **Read Connections**:
+ *   Retrieve all connections or get the current active connection.
+ *   ```typescript
+ *   const allConnections = ConnectionManager.getManager().getAllConnections();
+ *   const currentConnection = ConnectionManager.getManager().getCurrentConnection();
+ *   ```
+ *
+ * - **Delete a Connection**:
+ *   Remove a connection by name.
+ *   ```typescript
+ *   ConnectionManager.getManager().deleteConnection("Local Connection");
+ *   ```
+ *
+ * - **Set the Current Active Connection**:
+ *   Choose which connection will be the active one for CQL evaluations.
+ *   ```typescript
+ *   ConnectionManager.getManager().setCurrentConnection("Remote Connection");
+ *   ```
+ *
+ * **Context Management**:
+ *
+ * - **Adding or Updating a Context**:
+ *   Add or update a context within a specific connection. Contexts represent specific resources used in CQL evaluations (e.g., Patients).
+ *   ```typescript
+ *   const patientContext: Context = { resourceID: "123", resourceType: "Patient", resourceDisplay: "John Doe" };
+ *   ConnectionManager.getManager().upsertContext("Local Connection", patientContext);
+ *   ```
+ *
+ * - **Retrieving Contexts for the Current Connection**:
+ *   ```typescript
+ *   const contexts = ConnectionManager.getManager().getCurrentContexts();
+ *   console.log(contexts);
+ *   ```
+ *
+ * - **Deleting a Context**:
+ *   ```typescript
+ *   ConnectionManager.getManager().deleteContext("Local Connection", "Patient/123");
+ *   ```
+ *
+ * **Important Notes:**
+ *
+ * - **Context Parameters**:
+ *   Contexts represent specific resource types such as Patients, Encounters, or Organizations. Each connection may have multiple contexts,
+ *   but currently, only "Patient" is supported. Future updates will expand this to include other resource types.
+ *
+ * - **Single Active Connection**:
+ *   Only one connection can be active at a time. Switching between connections is managed by the `setCurrentConnection` method.
+ *
+ * **Considerations and Limitations:**
+ *
+ * - **FHIR-Only**: The connection manager is currently limited to managing FHIR-based data connections.
+ * - **Single Active Connection**: Only one connection may be active at a time for CQL evaluations.
+ * - **Context Limitations**: Only the "Patient" context parameter is currently supported. Other contexts like "Encounters" or "Organizations"
+ *   are expected to be supported in future updates.
+ *
+ * **Future Enhancements:**
+ *
+ * - **Additional Context Support**: Expand support to include other context types, such as Encounters and Organizations.
+ * - **Terminology Repositories**: Add support for managing connections to external terminology repositories.
+ * - **Artifact Repositories**: Include support for managing repositories of CQL artifacts (e.g., Libraries, PlanDefinitions, Measures).
+ * - **Multiple Active Connections**: Enable the possibility of managing and utilizing multiple active connections for more complex workflows.
+ *
+ * @param {ExtensionContext} ec - The extension context used to initialize the ConnectionManager.
  */
 export class ConnectionManager {
   private static connectionManager: ConnectionManager;

src/executeCql.ts

@@ -1,27 +1,74 @@
-/**
- * This is a stub description for now.
- */
 import * as fs from 'fs';
 import { Position, TextEditor, Uri, commands, window, workspace } from 'vscode';
 import { EvaluationParameters } from './buildParameters';
 import { Commands } from './commands';
 
 /**
- * Inserts a line of text at the end of the document in the given text editor.
- * @param {TextEditor} textEditor - The text editor where the text should be inserted.
- * @param {string} text - The text to insert.
- */
-async function insertLineAtEnd(textEditor: TextEditor, text: string) {
-  const document = textEditor.document;
-  await textEditor.edit(editBuilder => {
-    editBuilder.insert(new Position(textEditor.document.lineCount, 0), text + '\n');
-  });
-}
-
-/**
- * Executes CQL (Clinical Quality Language) based on the provided evaluation parameters.
- * Outputs results to a text document specified by the evaluation parameters.
- * @param {EvaluationParameters} evaluationParams - The parameters required for executing CQL.
+ * Executes Clinical Quality Language (CQL) operations based on the provided parameters.
+ *
+ * This function manages the execution of CQL commands by sending operation parameters to the CQL Language Server
+ * and capturing the results in a text file. The output includes messages that describe the execution environment
+ * (CQL file location, terminology, test cases, and context values), along with the results for each context.
+ *
+ * **Quick Example:**
+ *
+ * - **Executing CQL with Parameters**:
+ *   ```typescript
+ *   const evaluationParams: EvaluationParameters = {
+ *     operationArgs: ['-lu=/path/to/cql', '-t=/path/to/terminology', '-mu=/path/to/test'],
+ *     outputPath: Uri.parse("file:///path/to/output.txt"),
+ *     testPath: Uri.parse("file:///path/to/test")
+ *   };
+ *
+ *   await executeCQL(evaluationParams);
+ *   // Outputs the execution result to the specified output file.
+ *   ```
+ *
+ * **Purpose:**
+ *
+ * - **CQL Execution**: Interacts with the CQL Language Server to execute a CQL library or expression.
+ * - **Results Logging**: Manages and formats the execution output into a text file, displaying key context-related data and results.
+ * - **Timing**: Logs the elapsed time of the execution for performance analysis.
+ *
+ * **Execution Breakdown:**
+ *
+ * 1. **CQL Message**: Captures the CQL file's location using the `-lu=` argument.
+ * 2. **Terminology Message**: Captures terminology data location using the `-t=` argument.
+ * 3. **Test Data and Contexts**: Logs the test cases and context values found in the provided data.
+ *
+ * **Example Output in the Resulting Text File:**
+ *
+ * ```
+ * CQL: path/to/cql
+ * Terminology: /path/to/terminology
+ * Test cases:
+ * path/to/test - 123
+ * path/to/test - 456
+ *
+ * Patient 123:
+ * ... [execution result] ...
+ * Patient 456:
+ * ... [execution result] ...
+ * elapsed: 3.45 seconds
+ * ```
+ *
+ * **Functionality:**
+ *
+ * - Executes the CQL using `Commands.EXECUTE_WORKSPACE_COMMAND` and `Commands.EXECUTE_CQL`.
+ * - Inserts important messages and results into the output text file.
+ * - Interleaves context-related information with the results, enhancing readability.
+ *
+ * **Future Enhancements:**
+ *
+ * - Improve result formatting for better readability (e.g., JSON or other structured formats).
+ * - Add support for more complex result handling, such as different output file formats (e.g., CSV, XML).
+ *
+ * **Considerations:**
+ *
+ * - **Context-Related Execution**: The function supports multiple contexts and interleaves their corresponding results.
+ * - **File Output**: Currently, results are only saved in a text file format.
+ *
+ * @param {EvaluationParameters} evaluationParams - The parameters required for executing CQL. See {@link EvaluationParameters}.
  */
 export async function executeCQL({ operationArgs, testPath, outputPath }: EvaluationParameters) {
   let cqlMessage = '';
@@ -30,6 +77,7 @@ export async function executeCQL({ operationArgs, testPath, outputPath }: Evalua
   let foundTest = false;
   const contextValues: string[] = [];
 
+  // Loop through the operation arguments to build messages and find test data
   for (let i = 0; i < operationArgs?.length!; i++) {
     if (operationArgs![i].startsWith('-lu=')) {
       cqlMessage = `CQL: ${operationArgs![i].substring(4)}`;
@@ -49,17 +97,20 @@ export async function executeCQL({ operationArgs, testPath, outputPath }: Evalua
     }
   }
 
+  // Handle the case when no test data is found
   if (!foundTest) {
     testMessage = `No data found at path ${testPath!}. Evaluation may fail if data is required.`;
   }
 
+  // Open the output file and start inserting information
   const textDocument = await workspace.openTextDocument(outputPath!);
   const textEditor = await window.showTextDocument(textDocument);
 
   await insertLineAtEnd(textEditor, `${cqlMessage}`);
   await insertLineAtEnd(textEditor, `${terminologyMessage}`);
   await insertLineAtEnd(textEditor, `${testMessage}`);
 
+  // Start timing the execution
   const startExecution = Date.now();
   const result: string | undefined = await commands.executeCommand(
     Commands.EXECUTE_WORKSPACE_COMMAND,
@@ -68,9 +119,11 @@ export async function executeCQL({ operationArgs, testPath, outputPath }: Evalua
   );
   const endExecution = Date.now();
 
+  // Interleave results with context
   const expression = operationArgs?.find(arg => arg.startsWith('-e='))?.replace('-e=', '');
   await insertLineAtEnd(textEditor, attemptInterleave(expression, contextValues, result || ''));
 
+  // Log the execution time
   await insertLineAtEnd(
     textEditor,
     `elapsed: ${((endExecution - startExecution) / 1000).toString()} seconds`,
@@ -80,6 +133,16 @@ export async function executeCQL({ operationArgs, testPath, outputPath }: Evalua
 /**
  * Attempts to interleave test case names with result expressions for better readability.
  * Returns the result unmodified if unable to interleave.
+ *
+ * **Example of Interleaving Output**:
+ *
+ * ```
+ * Patient: 123
+ * ExpressionResult: ...
+ * Patient: 456
+ * ExpressionResult: ...
+ * ```
+ *
  * @param {string | undefined} expression - The CQL expression being evaluated.
  * @param {string[]} contextValues - The context values to interleave with the results.
  * @param {string} result - The result string to be interleaved.
@@ -115,3 +178,15 @@ const attemptInterleave = (
     return result;
   }
 };
+
+/**
+ * Inserts a line of text at the end of the document in the given text editor.
+ * @param {TextEditor} textEditor - The text editor where the text should be inserted.
+ * @param {string} text - The text to insert.
+ */
+async function insertLineAtEnd(textEditor: TextEditor, text: string) {
+  const document = textEditor.document;
+  await textEditor.edit(editBuilder => {
+    editBuilder.insert(new Position(textEditor.document.lineCount, 0), text + '\n');
+  });
+}

src/normalizeCqlExecution.ts

@@ -1,17 +1,72 @@
-/**
- * This is a stub description for now.
- */
 import { Uri, window } from 'vscode';
 import { buildParameters } from './buildParameters';
 import { executeCQL } from './executeCql';
 
 /**
- * Normalizes the execution of CQL based on the type of operation ('file' or 'expression').
+ * Normalizes the execution of CQL operations based on the type of operation ('file' or 'expression').
+ *
+ * This function serves as a **Gatekeeper** by validating the workspace environment and **Normalizing** the data
+ * required for execution. It takes VS Code-specific details, determines the type of operation to be executed
+ * (such as [$cql](https://build.fhir.org/ig/HL7/cql-ig/OperationDefinition-cql-cql.html), [$evaluate-measure](https://hl7.org/fhir/R4/measure-operation-evaluate-measure.html), [$apply](https://hl7.org/fhir/R4/plandefinition-operation-apply.html) for PlanDefinitions, or [$evaluate](https://build.fhir.org/ig/HL7/cql-ig/OperationDefinition-cql-library-evaluate.html) for Libraries), and standardizes
+ * this data into strings or URIs. These are then passed on to {@link buildParameters} for the construction of the
+ * necessary execution parameters, which are finally handed off to {@link executeCQL} to perform the execution.
+ *
+ * **Purpose:**
+ *
+ * - **Gatekeeper**: Validates the current state, ensuring the correct file type (CQL) and operation type (file or expression).
+ * - **Normalizer**: Takes workspace-specific details and standardizes them into a format suitable for execution.
+ * - **Executor**: Delegates the actual execution to the appropriate functions after normalizing the input data.
+ *
+ * **Quick Examples:**
+ *
+ * - **Executing a Full CQL File**:
+ *   ```typescript
+ *   const uri = URI.parse("file:///Users/developer/vscode-project/input/cql/my-library.cql");
+ *   await normalizeCqlExecution(uri, 'file');
+ *   // Executes the entire CQL file specified by the URI.
+ *   ```
+ *
+ * - **Executing a Single CQL Expression**:
+ *   ```typescript
+ *   const uri = URI.parse("file:///Users/developer/vscode-project/input/cql/my-library.cql");
+ *   await normalizeCqlExecution(uri, 'expression');
+ *   // Executes a single expression based on the current cursor position in the active editor.
+ *   ```
+ *
+ * **Dependencies:**
+ *
+ * - **Active Text Editor**: The function depends on the active text editor being open with the CQL file.
+ * - **CQL File Requirement**: The function currently only supports CQL files. In the future, support for Measure, PlanDefinition, and Questionnaire files may be added.
+ * - **Helper Functions**:
+ *   - **`{@link buildParameters}(uri, expression)`**: Collects all parameters required for execution.
+ *   - **`{@link executeCQL}(operationArgs)`**: Handles the actual execution of the CQL.
+ *
+ * **Considerations and Limitations:**
+ *
+ * - **Expression Execution**:
+ *   - The function relies on the presence of a valid CQL `define` statement on the current cursor line when executing a single expression.
+ *   - If no valid definition is found, an error message is displayed, and execution is halted.
+ *
+ * - **File Type Limitation**:
+ *   - Currently limited to `.cql` files. Future enhancements may include support for [Measure](https://hl7.org/fhir/R4/measure.html), [PlanDefinition](https://hl7.org/fhir/R4/plandefinition.html), and [Questionnaire](https://hl7.org/fhir/R4/questionnaire.html) files.
+ *
+ * **Future Enhancements:**
+ *
+ * - **Measurement Period**: Incorporate support for Measure files.
+ * - **PlanDefinition and Questionnaire Support**: Expand the function to handle these additional FHIR resources.
+ * - **Flexible Contexts**: Enable the function to handle more complex execution contexts beyond CQL, such as PlanDefinitions or other FHIR artifacts.
+ *
+ * **Error Handling**:
+ *
+ * - **No Active Editor**: Displays a message if no active text editor is found.
+ * - **Invalid File Type**: Displays a message if the current file is not a CQL file.
+ * - **Missing Definition**: Displays an error if no valid CQL definition is found on the selected line during expression execution.
  *
  * @param {Uri} uri - The URI of the file or resource.
  * @param {'file' | 'expression'} type - The type of operation: 'file' for full file execution, 'expression' for single expression execution.
  * @returns {Promise<void>} A promise that resolves when the execution is complete.
  */
+
 export async function normalizeCqlExecution(uri: Uri, type: 'file' | 'expression'): Promise<void> {
   const editor = window.activeTextEditor;
   if (!editor) {