@smile-digital-health/crl 1.2.1 → 4.47.0

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)
@@ -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
 
@@ -547,4 +582,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;
@@ -37,14 +39,32 @@ export declare class CRLAstBuilder extends AbstractParseTreeVisitor<ASTNode> imp
     private parseMeta;
     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 {};