0.6.0 Release - `calm-docify` Endpoint fails post NPM Publish

[LeighFinegold]

The calm-docify endpoint is failing in the 0.6.0 release due to issues with missing dependencies and unresolved imports in the docusaurus template bundle. This affects users trying to run calm docify after installing @finos/calm-cli globally.

Issue 1: Missing Runtime Dependencies (ts-node, json-schema-ref-parser)

The tsup configuration in cli intentionally does not bundle certain dependencies, including:

• ts-node
• @apidevtools/json-schema-ref-parser

Since these dependencies were marked as devDependencies, they are not installed when users install @finos/calm-cli globally via:

npm install -g @finos/calm-cli
calm docify --input model/document-system.json --output ./output --url-to-local-file-mapping model/url-to-file-directory.json

As a result, template processing fails due to missing dependencies.

First Failure (ts-node missing)

node:internal/modules/cjs/loader:1145
  throw err;
  ^
Error: Cannot find module 'ts-node'

After Installing ts-node, Next Failure (json-schema-ref-parser missing)

npm install -g ts-node
calm docify --input model/document-system.json --output ./output --url-to-local-file-mapping model/url-to-file-directory.json

One gets

node:internal/modules/cjs/loader:1145
  throw err;
  ^
Error: Cannot find module '@apidevtools/json-schema-ref-parser'

This suggests that any dependency not bundled will surface as a failure one after another if they are not included as a cli package.json dependency.

---

Possible Solutions to Issue 1

✅ Solution 1.1: Move Runtime Dependencies to dependencies in cli/package.json

To ensure ts-node and json-schema-ref-parser are installed with @finos/calm-cli, move them to regular dependencies.

Modify cli/package.json:

{
  "dependencies": {
    "ts-node": "^10.9.1",
    "@apidevtools/json-schema-ref-parser": "^10.1.0"
  }
}

Not Considered Solution

• Bundling ts-node, json-schema-ref-parser into the CLI
  • ❌ Not an option, as bundling these libraries caused corruption in index.js during the build process.

---

Issue 2: Template Bundle Contains TypeScript Files with Unresolved Imports

Even after resolving Issue 1, calm-docify still fails because the template transformer inside template-bundles is incorrectly packaged. Although the Template Processor (leveraged by docify) was setup to allow folks to provide a transformer for which ts-node internally transpiles dynamically, the npm published form of this endpoint overlooked that such transpile config is not available to the npm package user.

Failure 1: Incorrect Module Syntax in Transformer

error [_TemplateProcessor]:    ❌ Error loading transformer: Cannot use import statement outside a module
error [_TemplateProcessor]:    ❌ Error generating template: ❌ Error loading transformer: Cannot use import statement outside a module

This occurs because docusaurus-transformer.ts is published as TypeScript instead of JavaScript**.

Failure 2: Even After Transpiling, Missing Imports Remain

dist/template-bundles/docusaurus/docusaurus-transformer.ts:2:96 - error TS2307: Cannot find module '@finos/calm-shared' or its corresponding type declarations.

2 import {Architecture, CalmControl, CalmCore, CalmFlowTransition, CalmTemplateTransformer} from '@finos/calm-shared';
      

This happens because the transformer still expects @finos/calm-shared as an external module, but tsup bundled it inside the CLI, making it unavailable at runtime!.

---

Possible Solutions to Issue 2

✅ **Solution 2.1: Ensure all type information of shared is also published

• Ensure that all type definitions from @finos/calm-shared are properly included in the published @finos/calm-cli package.
• This might involve changing how tsup generates .d.ts files.
• I could see this being important for allowing folks to extend tooling?

✅ Solution 2.2: Bundle shared before leveraging and bundling into CLI

• Instead of keeping @finos/calm-shared separate, fully bundle it before incorporating it into cli.
• This ensures that no references to @finos/calm-shared exist in the final package.

---

Key Design Question

If we drop VSExtension support and therefore CommonJS support, does that change the project set-up for the CLI?

[LeighFinegold]

Closing issue as now both issues fixed as part of 0.6.2 release