feat: tighten TypeScript type declarations — replace `any` with Concerto model types

[mttrbrts]

Background

PRs #649 and #665 added TypeScript declaration files (.d.ts) for all packages in this monorepo. This was a significant infrastructure step: per-package tsconfig.json, build:types scripts, and publishing the types/ directory via the typings field in package.json.

The declarations are generated from existing JSDoc annotations using tsc --emitDeclarationOnly. Because the JSDoc is intentionally loose (using {*} or {object} in many places), the generated types contain approximately 200 occurrences of any across the five main packages. The types are structurally correct but not maximally useful for TypeScript consumers.

Goal

Tighten the key public API signatures so that the return types of the transformer classes reflect the actual Concerto DOM objects, rather than any.

Priority targets

The highest-value improvements are the round-trip methods on the transformer classes, since these are what downstream TypeScript consumers interact with most:

• CommonMarkTransformer — fromMarkdown, fromTokens, toTokens
• CiceroMarkTransformer — fromMarkdown, fromTokens, fromCiceroEdit, fromCommonMark, toCommonMark, toCiceroMarkUnwrapped
• TemplateMarkTransformer — toTokens, tokensToMarkdownTemplate
• HtmlTransformer — toHtml, toCiceroMark

Approach

The return types for these methods are Concerto model objects. @accordproject/concerto-core already ships its own TypeScript declarations (ClassDeclaration, ModelManager, Serializer, etc.), so the types are available to import.

The recommended approach is to update the JSDoc @returns and @param annotations in the source .js files and regenerate the declarations — rather than hand-editing .d.ts files, which would go out of sync.

For example, updating:

/**
 * @param {string} markdown
 * @returns {*} a Concerto object
 */
fromMarkdown(markdown) { ... }

to:

/**
 * @param {string} markdown
 * @returns {object} CommonMark DOM (JSON)
 */
fromMarkdown(markdown) { ... }

Or, for the highest fidelity, introducing @typedef declarations that reference the Concerto model schema types.

Non-goal

This issue is not asking for a full TypeScript rewrite of the source files. JSDoc-driven declaration emit is the right approach for this codebase. The goal is simply to make the generated .d.ts files more useful by improving the annotations that feed into them.

Related

• Add Typescript types #648 — original issue requesting TypeScript support
• feat: add typescript type declarations for all packages #649 — added TypeScript declaration infrastructure
• fix(*): remove generated test declaration files from types follow-up #665 — removed stale test declaration files

[codewithchotu]

Hi @mttrbrts, I would like to work on this issue.
The goal of improving the generated TypeScript declarations and replacing broad any return types with more accurate Concerto model types seems interesting and valuable for downstream consumers.

I’ll start by investigating the transformer method typings and the related JSDoc annotations, then work on tightening the return types accordingly.