Skip to content

Commit afb160d

Browse files
jreyno77jreyno77
committed
finished up buildParameters docs and added a typedoc config to clean up the end docs generated.
1 parent 9577591 commit afb160d

2 files changed

Lines changed: 225 additions & 4 deletions

File tree

‎src/buildParameters.ts‎

Lines changed: 222 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
/**
2-
* This is a stub description for now.
2+
* Couldn't find a way to surface this documentation section. Would love to include most of the information from the buildParameters method here.
33
*/
4+
45
import * as fs from 'fs';
56
import * as fse from 'fs-extra';
67
import { glob } from 'glob';
@@ -17,6 +18,223 @@ export type EvaluationParameters = {
1718

1819
/**
1920
* Builds the parameters required for CQL evaluation.
21+
*
22+
* This function gathers and constructs all the necessary operational arguments for invoking the CQL
23+
* Language Service CLI. It retrieves and organizes the data points from the local environment,
24+
* which include CQL files, terminology, and test data, to prepare for evaluation. Currently, only local
25+
* paths are supported, but the design anticipates potential future support for remote URLs or database
26+
* locations.
27+
*
28+
* **Quick Examples:**
29+
*
30+
* - **Local CQL File without Expression:**
31+
* ```typescript
32+
* const uri = URI.parse("file:///Users/developer/vscode-project/input/cql/my-library.cql");
33+
* const params = buildParameters(uri, undefined);
34+
* console.log(params);
35+
* // Output:
36+
* // {
37+
* // operationArgs: [
38+
* // "-fv=R4",
39+
* // "-op=/Users/developer/vscode-project/input/cql/cql-options.json",
40+
* // "-lu=/Users/developer/vscode-project/input/cql",
41+
* // "-ln=my-library",
42+
* // "-t=/Users/developer/vscode-project/input/vocabulary/valueset",
43+
* // "-m=FHIR",
44+
* // "-c=Patient"
45+
* // ],
46+
* // outputPath: URI.parse("file:///Users/developer/vscode-project/input/tests/results/my-library.txt"),
47+
* // testPath: URI.parse("file:///Users/developer/vscode-project/input/tests")
48+
* // }
49+
* ```
50+
*
51+
* - **Local CQL File with Expression:**
52+
* ```typescript
53+
* const params = buildParameters(uri, "myExpression");
54+
* console.log(params);
55+
* // Output:
56+
* // {
57+
* // operationArgs: [
58+
* // "-fv=R4",
59+
* // "-op=/Users/developer/vscode-project/input/cql/cql-options.json",
60+
* // "-lu=/Users/developer/vscode-project/input/cql",
61+
* // "-ln=my-library",
62+
* // "-e=myExpression",
63+
* // "-t=/Users/developer/vscode-project/input/vocabulary/valueset",
64+
* // "-m=FHIR",
65+
* // "-c=Patient"
66+
* // ],
67+
* // outputPath: URI.parse("file:///Users/developer/vscode-project/input/tests/results/my-library.txt"),
68+
* // testPath: URI.parse("file:///Users/developer/vscode-project/input/tests")
69+
* // }
70+
* ```
71+
*
72+
* - **Remote Connection with Expression:**
73+
* ```typescript
74+
* // Assuming ConnectionManager is configured to use a remote connection.
75+
* const params = buildParameters(uri, "myExpression");
76+
* console.log(params);
77+
* // Output:
78+
* // {
79+
* // operationArgs: [
80+
* // "-fv=R4",
81+
* // "-op=/Users/developer/vscode-project/input/cql/cql-options.json",
82+
* // "-lu=/Users/developer/vscode-project/input/cql",
83+
* // "-ln=my-library",
84+
* // "-e=myExpression",
85+
* // "-t=/Users/developer/vscode-project/input/vocabulary/valueset",
86+
* // "-m=FHIR",
87+
* // "-mu=remote-url",
88+
* // "-c=Patient"
89+
* // ],
90+
* // outputPath: URI.parse("file:///Users/developer/vscode-project/input/tests/results/my-library.txt"),
91+
* // testPath: URI.parse("remote-url")
92+
* // }
93+
* ```
94+
*
95+
* **Dependencies:**
96+
*
97+
* - **Active Editor Requirement:**
98+
* The function is currently dependent on the active text editor being open with the CQL file.
99+
* This is because the FHIR version is extracted from the open document. Ideally, this should
100+
* be refactored to read from a file based on the URI to remove this dependency.
101+
* See: [VS Code Active Text Editor Documentation](https://code.visualstudio.com/api/references/vscode-api#window.activeTextEditor).
102+
*
103+
* - **Connection Manager:**
104+
* The function heavily relies on the {@link ConnectionManager} to determine the context and connection
105+
* details, particularly when working with remote connections. If a remote connection is active,
106+
* the function can use the remote connection URL as the test data path.
107+
*
108+
* **Operational Components:**
109+
*
110+
* 1. **CQL Data:**
111+
* - The main CQL file specified by the `uri` parameter.
112+
* - Extracts the `libraryName` and `libraryDirectory` from the given URI.
113+
*
114+
* 2. **Terminology Data:**
115+
* - Points to local terminology files located in `input/vocabulary/valueset`.
116+
*
117+
* 3. **Test Data and Results:**
118+
* - Test data is expected in `input/tests`, with results being saved in `input/tests/results`.
119+
* - If a remote connection is active, the test data path may point to a remote URL instead.
120+
*
121+
* @remarks
122+
*
123+
* Build Parameters is meant to provide the extension with the capability of building a set of parameters
124+
* to reflect the execution requirements of the Language Service CLI.
125+
*
126+
* There is an expected format for the retrieval of necessary data required to build these parameters.
127+
* Those are identified as Module level constants.
128+
*
129+
* **Visual Representations:**
130+
*
131+
* ```
132+
* file:///Users/developer/vscode-project/input/cql/my-library.cql
133+
* \___________________________________/ \____/\_______/\____________/
134+
* projectPath input lib_dir my-library.cql
135+
* ```
136+
*
137+
* ```
138+
* ..projectPath/input/vocabulary/valueset
139+
* \____/ \_________________/
140+
* input vocabulary/valueset
141+
* ```
142+
*
143+
* ```
144+
* ..projectPath/input/tests/results/my-library.txt
145+
* \____/ \____/ \______/\___________/
146+
* input tests results my-library.txt
147+
* ```
148+
*
149+
* **Example usage:**
150+
*
151+
* Given the following URI for a CQL file in a VS Code extension project:
152+
*
153+
* `uri: "file:///Users/developer/vscode-project/input/cql/my-library.cql"`
154+
*
155+
* **Breakdown of Example URI:**
156+
*
157+
* 1. **CQL:**
158+
* - projectPath: `"file:///Users/developer/vscode-project"`
159+
* - input: `"input"`
160+
* - cql directory: `"cql"`
161+
* - file name: `"my-library.cql"`
162+
*
163+
* 2. **Terminology:**
164+
* - input: `"input"`
165+
* - subdirectory: `"vocabulary/valueset"`
166+
*
167+
* 3. **Data/Results:**
168+
* - input: `"input"`
169+
* - test directory: `"tests"`
170+
* - results directory: `"results"`
171+
* - output file: `"my-library.txt"`
172+
*
173+
* **Derived Constants:**
174+
*
175+
* - **projectPath:** `"file:///Users/developer/vscode-project"`
176+
* - The root path of the VS Code workspace.
177+
*
178+
* - **libraryDirectory:** `"file:///Users/developer/vscode-project/input/library"`
179+
* - The directory containing the CQL file.
180+
*
181+
* - **libraryName:** `"my-library"`
182+
* - The base name of the CQL file.
183+
*
184+
* - **terminologyPath:** `"file:///Users/developer/vscode-project/input/vocabulary/valueset"`
185+
* - The path to the terminology files (value sets).
186+
*
187+
* - **testPath:** `"file:///Users/developer/vscode-project/input/tests"`
188+
* - The path to test cases related to the CQL file.
189+
*
190+
* - **resultPath:** `"file:///Users/developer/vscode-project/input/tests/results"`
191+
* - The directory where execution results will be stored.
192+
*
193+
* - **outputPath:** `"file:///Users/developer/vscode-project/input/tests/results/my-library.txt"`
194+
* - The full path to the output file containing the evaluation results.
195+
* ---
196+
* **Considerations and Limitations:**
197+
*
198+
* - **Measurement Period:**
199+
* *Currently not implemented; a default parameter is used during CQL execution.*
200+
*
201+
* - **FHIR as the Data Model:**
202+
* *The function is limited to using FHIR as the data model.*
203+
*
204+
* - **CQL Options File Location:**
205+
* *The `cql-options.json` file must be located in the same directory as the CQL libraries.*
206+
*
207+
* - **Library Name Dependency:**
208+
* *The library name must be part of the CQL file name.*
209+
*
210+
* - **Context Limitations:**
211+
* *The function is currently limited to handling the "Patient" context.*
212+
*
213+
* ---
214+
*
215+
* **Future Enhancements:**
216+
*
217+
* - **Measurement Period:**
218+
* *Add support for defining and using measurement periods within CQL execution parameters.*
219+
*
220+
* - **Support for Additional Data Models:**
221+
* *Expand support beyond FHIR to include other data models.*
222+
*
223+
* - **Flexible CQL Options File Location:**
224+
* *Allow the `cql-options.json` file to be located in different directories or derive its path dynamically.*
225+
*
226+
* - **Automatic Library Name Extraction:**
227+
* *Automatically derive the library name from the CQL file content, removing the dependency on the file name.*
228+
*
229+
* - **Expanded Context Support:**
230+
* *Enable support for multiple contexts, such as Encounters or Organizations, for more complex CQL evaluations.*
231+
*
232+
* - **Remote URLs and Database Connections:**
233+
* *Support retrieving CQL, terminology, and test data from remote URLs or databases.*
234+
*
235+
* - **Refactor FHIR Version Extraction:**
236+
* *Eliminate the dependency on the active text editor by extracting the FHIR version directly from the CQL file.*
237+
*
20238
* @param {URI} uri - The URI of the CQL file.
21239
* @param {string | undefined} expression - The specific CQL expression to evaluate, if any.
22240
* @returns {EvaluationParameters} The parameters required for the CQL evaluation.
@@ -35,12 +253,12 @@ export function buildParameters(uri: URI, expression: string | undefined): Evalu
35253
const libraryName = Utils.basename(uri).replace('.cql', '').split('-')[0];
36254
const projectPath = workspace.getWorkspaceFolder(uri)!.uri;
37255
const terminologyPath: URI = Utils.resolvePath(projectPath, 'input', 'vocabulary', 'valueset');
38-
const fhirVersion = getFhirVersion();
39-
const optionsPath = Utils.resolvePath(libraryDirectory, 'cql-options.json');
40-
const measurementPeriod = '';
41256
const testPath = Utils.resolvePath(projectPath, 'input', 'tests');
42257
const resultPath = Utils.resolvePath(testPath, 'results');
43258
const outputPath = Utils.resolvePath(resultPath, `${libraryName}.txt`);
259+
const fhirVersion = getFhirVersion();
260+
const optionsPath = Utils.resolvePath(libraryDirectory, 'cql-options.json');
261+
const measurementPeriod = '';
44262
const connectionManager = ConnectionManager.getManager();
45263

46264
fse.ensureFileSync(outputPath.fsPath);

‎typedoc.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"excludeNotDocumented": true
3+
}

0 commit comments

Comments
 (0)