@smile-digital-health/crl 1.2.1 → 4.92.1

package/LICENSE

@@ -198,4 +198,4 @@ Apache License
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -6,10 +6,14 @@ Clinical Reasoning Language (CRL) provides a structured way to model clinical de
 
 ## Overview
 
-See the [User Guide](./USER_GUIDE.md) for a comprehensive introduction to the CRL language, syntax, and authoring best practices.
+See the [User Guide](./USER_GUIDE.md) for a comprehensive introduction to the CRL language, syntax, and authoring best practices. For the **CLI and MCP tool reference** (emit, validate, the 7 MCP tools — for both CRL and CEL), see [TOOLING.md](./TOOLING.md).
 
 CRL is a domain-specific language designed for expressing clinical practice guidelines in a structured and machine-readable format. The language is implemented in TypeScript and provides a comprehensive set of tools for processing CRL documents.
 
+## Metadata annotations
+
+CRL concepts can carry typed metadata via an `@tag` convention on `meta` lines (e.g. `@description`, `@ke-feedback`, `@kg-concept`) — for descriptions, knowledge-engineer feedback, plain-language logic, external-store hints, and extraction provenance. See the [metadata model](./spec/metadata-model.md) and the canonical [tag registry](./spec/metadata-registry.json). *(Draft: the convention parses today; Validator enforcement is forthcoming.)*
+
 ## Installation
 
 This is a private package. To install it, you need:
@@ -66,12 +70,31 @@ npm pack
 tar -ztvf <package-name>.tgz
 ```
 
+#### Cutting a release (build both artifacts + upload to GitHub)
+
+Releases ship two artifacts side-by-side: the npm tarball (`smile-digital-health-crl-<version>.tgz`) and the VS Code extension VSIX (`crl-language-support-<version>.vsix`).
+
+**Heads-up (Windows):** if you have VS Code open with the CRL extension active, its bundled MCP server keeps `dist/` files open and both `npm pack` and `npm run package` will fail with `EPERM` on `dist/`. Close VS Code (or just disable the CRL extension) before running the build commands below.
+
+```bash
+# 1. Close VS Code (or disable the CRL extension) so the MCP server releases any lock on dist/.
+# 2. From the repo root, build the npm tarball for the core package:
+npm pack -w @smile-digital-health/crl
+
+# 3. Build the extension VSIX (also from the repo root):
+npm run package -w crl-language-support
+
+# 4. Upload the resulting .tgz and .vsix to the corresponding GitHub release.
+```
+
+Both artifacts are produced at the version declared in their respective `package.json` files. Bump those (and tag the commit `v<version>`) before running the steps above so the produced filenames match the release tag.
+
 ## Features
 
 ### Language Features
 
 * Decision blocks with nested conditions
-* Concept definitions with type and optional value specifications
+* Concept definitions with type and value specifications
 * Activity statements with perform types
 * Terminology statements with valueset, system/code, and unknown definitions
 * FHIR resource type support
@@ -176,6 +199,18 @@ npm run cli:lexer
 
 Replace `<module>` with the desired CLI module name (e.g., `lexer`, `parser`, etc.).
 
+## FHIR Definition Emit (v2.4.0)
+
+CRL emits CPG-IG-conformant FHIR Definition resources (ValueSet, Library, ActivityDefinition, PlanDefinition) alongside the existing CQL emit.
+
+```bash
+crl-emit --path <root.crl> --out-dir <project-root> --target fhir-def
+```
+
+Output lands at `<project-root>/fhir/<ResourceType>/<id>.json`. CQL emit (the existing `--target cql` / default behavior) lands at `<project-root>/cql/<library-name>.cql`. Library content references the CQL file via the relative path `../../cql/<library-name>.cql`.
+
+For semantic rules, layout details, deliberate spec deviations, and the MCP `emit_crl_fhir` tool, see [`USER_GUIDE.md` §"Emitting FHIR Definition resources"](USER_GUIDE.md#emitting-fhir-definition-resources).
+
 ## API Usage & Reference
 
 **All API functions return a `ParseResult` object. If there are any lexical or syntax errors, these are collected and returned in the `errors` array (not just printed to the console). You should always check `result.success` and handle errors accordingly.**
@@ -304,7 +339,7 @@ The comparison includes:
 
 ### FSH-to-CRL Example Data
 
-The example FSH files and CRL outputs in `examples/fsh/who/smart-example-immz/` and `examples/crl/who/smart-example-immz/` are derived from the [WHO SMART Guidelines - Example IG for Measles Immunization](https://github.com/WorldHealthOrganization/smart-example-immz).
+The example FSH files and CRL outputs in `src/examples/fsh/who/smart-example-immz/` and `src/examples/crl/who/smart-example-immz/` are derived from the [WHO SMART Guidelines - Example IG for Measles Immunization](https://github.com/WorldHealthOrganization/smart-example-immz).
 
 - **Source repository:** [WorldHealthOrganization/smart-example-immz](https://github.com/WorldHealthOrganization/smart-example-immz)
 - **License:** [CC BY-IGO 3.0](https://github.com/WorldHealthOrganization/smart-example-immz/blob/main/LICENSE.md)
@@ -370,8 +405,8 @@ npm test
 # Run tests with coverage
 npm run test:coverage
 
-# Run specific test files
-npx jest src/ast/tests/decision-structure.test.ts --verbose --no-cache --colors --forceExit --detectOpenHandles --watchAll=false 
+# Run specific test files (vitest positional filter — substring match on the test path)
+npx vitest run --root ../.. --project crl src/ast/tests/decision-structure.test.ts
 
 # Run tests in watch mode (useful during development)
 npm run test:watch
@@ -476,7 +511,7 @@ Note: This project uses a custom AST implementation that uses ANTLR's visitor pa
 >
 > The authoritative release checklist and instructions are maintained in a single location:
 > 
-> **[.github/PULL_REQUEST_TEMPLATE/release.md](.github/PULL_REQUEST_TEMPLATE/release.md)**
+> **[.github/PULL_REQUEST_TEMPLATE/release.md](../../.github/PULL_REQUEST_TEMPLATE/release.md)**
 >
 > Always follow the steps in this file when preparing a new release. This ensures consistency and reduces maintenance overhead. If you need to update the release process, update the PR template only.
 
@@ -490,7 +525,7 @@ Note: This project uses a custom AST implementation that uses ANTLR's visitor pa
 - **Generated Files:** Auto-generated files (e.g., ANTLR outputs, grammar-driven types) are ignored by git and should never be edited manually. Always use the provided scripts to regenerate them.
 - **Documentation:** Keep all documentation referencing the release checklist up-to-date by linking to the PR template.
 
-For more details, see the [release PR template](.github/PULL_REQUEST_TEMPLATE/release.md) and the automation scripts in `.github/scripts/`.
+For more details, see the [release PR template](../../.github/PULL_REQUEST_TEMPLATE/release.md) and the automation scripts in `.github/scripts/`.
 
 ### Error Handling Strategy
 
@@ -521,23 +556,9 @@ This project implements robust, layered error handling across all stages of the
 }
 ```
 
-#### Clean Test Output: Suppressing Console Errors in Jest
+#### Test Output and Console Errors
 
-To keep test output clean and focused on actual test failures, all `console.error` output is globally suppressed during tests. This is achieved by adding the following to `jest.setup.js`:
-
-```js
-beforeAll(() => {
-  jest.spyOn(console, 'error').mockImplementation(() => {});
-});
-```
-
-And registering it in `jest.config.js`:
-
-```js
-setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
-```
-
-This ensures that error logs are visible during development and CLI runs, but do not clutter test output.
+These tests run on [vitest](https://vitest.dev/) (migrated from jest). There is intentionally **no** global `console.error` suppression: a global mute made real failure diagnostics dead code, and the muted lines only fire on failure paths anyway (so removing it added no noise on green runs). A suite that intentionally exercises an error path mutes `console.error` locally instead — e.g. `vi.spyOn(console, "error").mockImplementation(() => {})` scoped to that test, restored after.
 
 ## Editor Support: VS Code Extension
 
@@ -547,4 +568,9 @@ We provide a Visual Studio Code extension for CRL files:
 - Comment support
 - Language basics for a better editing experience
 
-For installation instructions and full details, see [extension/README.md](./extension/README.md)
+For installation instructions and full details, see [crl-vscode/README.md](../crl-vscode/README.md)
+
+## License
+
+This project is licensed under the Apache License 2.0.
+See the LICENSE file for details.

package/dist/ast/builder.d.ts

@@ -1,26 +1,28 @@
 import { ParserRuleContext } from "antlr4ts/ParserRuleContext";
 import { AbstractParseTreeVisitor } from "antlr4ts/tree/AbstractParseTreeVisitor";
-import { CrlContext, DecisionStatementContext, DecisionBodyContext, WhenBlockContext, BlockBodyContext, ActionStatementContext, RecommendStatementContext, UseStatementContext, TerminologyStatementContext, TerminologyValuesetContext, ActivityStatementContext, ConceptStatementContext, InferredFromBodyContext, InferredFromExpressionContext, InformalOrContext, InformalAndContext, InformalNotContext, AtomContext, WhenWithBodyContext, WhenSingleActionContext, NestedWhenBlockContext, BlockActionContext, BlockStatementContext } from "../grammar/generated/antlr/CRLParser";
+import { CrlContext, DecisionStatementContext, DecisionBodyContext, BranchItemContext, BlockBodyContext, ActionItemContext, ActionStatementContext, RecommendStatementContext, UseStatementContext, TerminologyStatementContext, TerminologyValuesetContext, ActivityStatementContext, ConceptStatementContext, ParameterStatementContext, LibraryStatementContext, IncludeStatementContext, DefinitionIsBodyContext, DefinedAsBodyContext, DefinedAsBareRefContext, DefinedAsCompositionContext, CompositionExpressionContext, SemOrContext, SemAndContext, SemNotContext, CompositionRefContext, CompositionGroupContext, NarrativeContext, NConceptRefContext, NQuantityContext, NWordContext, NArgGroupElementContext, QuantityContext, ArgGroupContext, ArgDisjunctionContext, ArgConjunctionContext, ArgSingletonContext, AVConceptRefContext, AVQuantityContext, AVNestedGroupContext, WhenWithBodyContext, WhenSingleActionContext, OtherwiseWithBodyContext, OtherwiseSingleActionContext } from "../grammar/generated/antlr/CRLParser";
 import { CRLParserVisitor } from "../grammar/generated/antlr/CRLParserVisitor";
 import type { CRLError } from "../types/errors";
-import { ASTNode, Decision, DecisionBody, WhenBlock, BlockBody, ActionStatement, RecommendActivity, UseDecision, Terminology, TerminologyValueset, TerminologySystem, TerminologyCode, Activity, ActivityBody, ActivityRequest, ActivityWith, ActivityBecause, Concept, ConceptReference, InformalAnd, InformalOr, NotExpression, GroupExpression, InferredFromConcept } from "./types";
-import type { CRL } from "./types";
-type InformalNode = GroupExpression | ConceptReference | InformalAnd | NotExpression | InformalOr;
+import { ASTNode, Decision, DecisionBody, WhenBlock, OtherwiseBlock, BranchBlock, BlockBody, ActionStatement, RecommendActivity, UseDecision, Terminology, TerminologyValueset, TerminologySystem, TerminologyCode, Activity, ActivityBody, ActivityRequest, ActivityWith, ActivityBecause, Concept, Parameter, DefinedAsDefinition, DefinedAsBareRef, DefinedAsComposition, CompositionExpression, CompositionRef, CompositionGroup, DefinitionIsDefinition, NarrativeClause, NConceptRef, NWord, NDisjunction, NConjunction, Quantity } from "./types";
+import type { CRL, LibraryDeclaration, Include } from "./types";
 export declare class CRLAstBuilder extends AbstractParseTreeVisitor<ASTNode> implements CRLParserVisitor<ASTNode> {
     private readonly errors;
     protected defaultResult(): ASTNode;
     getErrors(): CRLError[];
     protected reportError(message: string, ctx: ParserRuleContext, details?: Record<string, unknown>): void;
     visitCrl(ctx: CrlContext): CRL;
+    visitLibraryStatement(ctx: LibraryStatementContext): LibraryDeclaration;
+    visitIncludeStatement(ctx: IncludeStatementContext): Include;
     visitDecisionStatement(ctx: DecisionStatementContext): Decision;
     visitDecisionBody(ctx: DecisionBodyContext): DecisionBody;
-    visitWhenBlock(ctx: WhenBlockContext): WhenBlock;
+    visitBranchItem(ctx: BranchItemContext): BranchBlock;
     visitWhenWithBody(ctx: WhenWithBodyContext): WhenBlock;
     visitWhenSingleAction(ctx: WhenSingleActionContext): WhenBlock;
-    visitNestedWhenBlock(ctx: NestedWhenBlockContext): WhenBlock;
-    visitBlockStatement(ctx: BlockStatementContext): WhenBlock | ActionStatement;
+    visitOtherwiseWithBody(ctx: OtherwiseWithBodyContext): OtherwiseBlock;
+    visitOtherwiseSingleAction(ctx: OtherwiseSingleActionContext): OtherwiseBlock;
     visitBlockBody(ctx: BlockBodyContext): BlockBody;
-    visitBlockAction(ctx: BlockActionContext): ActionStatement;
+    visitActionItem(ctx: ActionItemContext): ActionStatement;
+    private buildActionGuard;
     visitActionStatement(ctx: ActionStatementContext): ActionStatement;
     visitRecommendStatement(ctx: RecommendStatementContext): RecommendActivity;
     visitUseStatement(ctx: UseStatementContext): UseDecision;
@@ -34,17 +36,35 @@ export declare class CRLAstBuilder extends AbstractParseTreeVisitor<ASTNode> imp
     visitActivityWith(ctx: import("../grammar/generated/antlr/CRLParser").ActivityWithContext): ActivityWith;
     visitActivityBecause(ctx: import("../grammar/generated/antlr/CRLParser").ActivityBecauseContext): ActivityBecause;
     private parseConceptTypes;
-    private parseMeta;
+    private metaFrom;
     private parseEvidence;
     private parseConceptDefinition;
+    private buildCodedFrom;
+    private parseCode;
+    private parseRepresentations;
+    visitParameterStatement(ctx: ParameterStatementContext): Parameter;
     visitConceptStatement(ctx: ConceptStatementContext): Concept;
-    visitDefinitionConcept(ctx: InferredFromBodyContext): InferredFromConcept;
-    visitDefinitionLogic(ctx: InferredFromBodyContext): GroupExpression | InferredFromConcept;
-    visitInferredFromExpression(ctx: InferredFromExpressionContext): InformalNode;
-    visitInformalOr(ctx: InformalOrContext): InformalOr;
-    visitInformalAnd(ctx: InformalAndContext): InformalAnd | NotExpression | GroupExpression | ConceptReference;
-    visitInformalNot(ctx: InformalNotContext): import("./types").InferredFromExpression;
-    visitConceptAtom(ctx: AtomContext): ConceptReference;
-    visitGroupExpression(ctx: AtomContext): GroupExpression;
+    visitDefinedAsBareRef(ctx: DefinedAsBareRefContext): DefinedAsBareRef;
+    visitDefinedAsComposition(ctx: DefinedAsCompositionContext): DefinedAsComposition;
+    visitCompositionExpression(ctx: CompositionExpressionContext): CompositionExpression;
+    visitSemOr(ctx: SemOrContext): CompositionExpression;
+    visitSemAnd(ctx: SemAndContext): CompositionExpression;
+    visitSemNot(ctx: SemNotContext): CompositionExpression;
+    visitCompositionRef(ctx: CompositionRefContext): CompositionRef;
+    visitCompositionGroup(ctx: CompositionGroupContext): CompositionGroup;
+    visitDefinedAsBody(ctx: DefinedAsBodyContext): DefinedAsDefinition;
+    visitDefinitionIsBody(ctx: DefinitionIsBodyContext): DefinitionIsDefinition;
+    visitNarrative(ctx: NarrativeContext): NarrativeClause;
+    visitNConceptRef(ctx: NConceptRefContext): NConceptRef;
+    visitNQuantity(ctx: NQuantityContext): Quantity;
+    visitNWord(ctx: NWordContext): NWord;
+    visitNArgGroupElement(ctx: NArgGroupElementContext): NDisjunction | NConjunction | NConceptRef | Quantity;
+    visitQuantity(ctx: QuantityContext): Quantity;
+    visitArgGroup(ctx: ArgGroupContext): NDisjunction | NConjunction | NConceptRef | Quantity;
+    visitArgDisjunction(ctx: ArgDisjunctionContext): NDisjunction;
+    visitArgConjunction(ctx: ArgConjunctionContext): NConjunction;
+    visitArgSingleton(ctx: ArgSingletonContext): NConceptRef | Quantity | NDisjunction | NConjunction;
+    visitAVConceptRef(ctx: AVConceptRefContext): NConceptRef;
+    visitAVQuantity(ctx: AVQuantityContext): Quantity;
+    visitAVNestedGroup(ctx: AVNestedGroupContext): NDisjunction | NConjunction | NConceptRef | Quantity;
 }
-export {};