Expose CALM as a Library for Extension and Template Use

[LeighFinegold]

Context

As part of the ongoing effort to make CALM more modular and developer-friendly, we want to expose CALM models and utilities in a reusable way so that consumers (e.g., template authors) can import and extend the architecture model and related tooling.

This issue aims to clarify:

• What parts of CALM should be exposed
• How we should structure and publish those parts

---

❓ What to Expose

We currently have two main directions:

1. Just the Model

   • Expose CalmArchitecture, CalmNode, CalmRelationship, etc.
   • Enough to allow template bundles to build visitors or augment the model

2. Full Utility Set (Shared)

   • Expose everything from @finos/calm-shared, including schema resolution, parsing, loading, error handling, etc.
   • This would empower more advanced extensions, such as validators or custom CLI plugins

---

📦 How to Expose

We have two main packaging options:

Option 1: Expose via @calm-cli

Users would import like this:

import { CalmArchitecture } from '@calm-cli/model/CalmArchitecture'

Pros:

• Keeps everything in one package
• Easy for template developers already using the CLI

Cons:

• CLI-focused name might confuse library users
• Less modular

---

Option 2: Separate Package like @calm-model or @calm/core

Users would import like this:

import { CalmArchitecture } from '@calm-model'

Pros:

• Clean separation of concerns
• Easier for external consumers to depend on CALM without pulling in CLI or non-core features
• Better long-term for maintaining semantic versioning

Cons:

• More packages to manage
• Slight overhead for releases

---

✅ Proposal (Open for Discussion)

• Short-Term: Expose core models via @calm-cli/model/* to unblock template development
• Long-Term: Consider creating a dedicated package like @finos/calm-model (or @finos/calm-shared) that houses all shared definitions and utilities

---

👀 Questions

• Do template authors need more than the model and calm doc parser (e.g., validator, schema resolution, graphing,c4 tooling)?

[Thels]

Interface that needs to be included is CalmTemplateTransformer.ts - as that will be required as part of the custom transformers to adhere to the interface.

Another option to consider - creating a model module - which shared depends on - which is published with the same version as the CLI.

[LeighFinegold]

Discussed on https://github.com/finos/architecture-as-code/issues/1078

Agreed to publish @calm/model (assuming it can be published like that rather than @calm-model). This will contain an easier to work with model and also schema types.

Agreed to publish @calm/core (this would contain functional code code). A further discussion to expose everything vs a few. Keep @calm/cli as cut down library.

Both @calm/model and @calm/core will expose the type definitions so others can use as a library code.

Agreed that all 3 npm packages will use the same version. We should ideally define on root and apply to all sub modules.

We need to potentially send email to @finos to expose those new modules

[rocketstack-matt]

Is the intend these all get published to nom? Is so @finos will be the parent org don't the packages need to be:

• @finos/calm-cli
• @finos/calm-shared
• @finos/calm-model
• @finos/calm-core

[LeighFinegold]

Discussed on https://github.com/finos/architecture-as-code/issues/1453 and decided that the schema for CALM has now reached a state where it is locked down. We no longer feel the need to expose the model.

Concern was raised around folks writing their own bundles using typescript and wanting to leverage the interface that index.json expects i.e. CalmTemplateTransformer.ts. This will be re-addressed in future releases.

@rocketstack-matt @Thels @markscott-ms