Repository navigation
fix(concerto-core): remove ESM entrypoint from sideEffects to enable package-level tree shaking - #1263
fix(concerto-core): remove ESM entrypoint from sideEffects to enable package-level tree shaking#1263mttrbrts wants to merge 8 commits into
Conversation
|
Hi @mttrbrts, I think I would prefer |
|
This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed. |
|
@github unstale |
|
This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed. |
|
@github unstale |
|
This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed. |
Signed-off-by: Rishabh Jain <rishabhj2005@email.com>
…package-level tree shaking Listing `./dist/esm/index.mjs` in sideEffects prevented bundlers from skipping concerto-core entirely when nothing from it is imported. Instead, emit `dist/esm/dayjs-setup.js` as a separate file and reference that in sideEffects — keeping the real side effect (dayjs.extend() calls) declared while allowing the main ESM bundle to be tree-shaken at the package boundary. Verified: importing only concerto-util produces a 59 KB bundle; adding concerto-core jumps to 1.46 MB, confirming the package is correctly excluded when unused. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk>
The ESM dayjs-setup output lived at dist/esm/dayjs-setup.js. Since the package is not "type": "module", Node parses a .js file as CommonJS, so an ESM file with that extension is ambiguous. Emit it as .mjs and point the sideEffects entry at the .mjs path so the dayjs.extend() side effect stays correctly declared. Also document in DEVELOPERS.md that the monorepo must be built in dependency order (npm run build), because each package's exports.import now resolves to dist/esm/index.mjs. Addresses review feedback on PR #1263. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk>
6957f72 to
3073809
Compare
There was a problem hiding this comment.
Pull request overview
This PR makes the published @accordproject/* packages tree-shakeable at the package boundary by adding an additive ESM build (dist/esm/index.mjs), conditional exports, and accurate sideEffects metadata (with concerto-core isolating the dayjs.extend() side effect into a dedicated module).
Changes:
- Add an esbuild-based ESM build step across workspace packages and wire it into package builds.
- Introduce conditional
exports+modulefields and mark packages as side-effect-free (exceptconcerto-core, which whitelistsdayjs-setup). - Consolidate all
dayjs.extend()calls intoconcerto-core/src/dayjs-setup.tsand add browser E2E coverage via Playwright + CI.
Reviewed changes
Copilot reviewed 22 out of 23 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/build-esm.js | New shared ESM build script (esbuild) used by workspace packages. |
| package.json | Adds Playwright + esbuild dev deps, includes e2e workspace, and adds a root test:e2e script. |
| package-lock.json | Lockfile updates for added dependencies/workspace. |
| DEVELOPERS.md | Documents the need to build the monorepo in dependency order for ESM outputs. |
| .github/workflows/build.yml | Adds a Chromium Playwright E2E job to CI. |
| e2e/.gitignore | Ignores Playwright artifacts and node_modules for the new E2E workspace. |
| e2e/package.json | New E2E workspace package and scripts to build then run Playwright tests. |
| e2e/playwright.config.ts | Playwright runner configuration for Chromium project. |
| e2e/tests/browser-bundles.spec.ts | New browser smoke tests to validate UMD bundles and dayjs plugin behavior. |
| packages/concerto-analysis/package.json | Adds ESM build step + exports/module/sideEffects metadata. |
| packages/concerto-core/package.json | Adds ESM build step + conditional exports and sideEffects whitelist for dayjs setup files. |
| packages/concerto-core/src/dayjs-setup.ts | New consolidated dayjs plugin registration module. |
| packages/concerto-core/src/datetimeutil.ts | Switches to importing dayjs via the consolidated setup module. |
| packages/concerto-core/src/factory.ts | Switches to importing dayjs via the consolidated setup module. |
| packages/concerto-core/src/model/typed.ts | Switches to importing dayjs via the consolidated setup module. |
| packages/concerto-core/src/serializer/jsonpopulator.ts | Switches to importing dayjs via the consolidated setup module. |
| packages/concerto-core/src/serializer/resourcevalidator.ts | Switches to importing dayjs via the consolidated setup module. |
| packages/concerto-core/src/serializer/valuegenerator.ts | Switches to importing dayjs via the consolidated setup module. |
| packages/concerto-cto/package.json | Adds ESM build step + exports/module/sideEffects metadata. |
| packages/concerto-linter/package.json | Adds ESM build step + exports/module/sideEffects metadata. |
| packages/concerto-util/package.json | Adds ESM build step + exports/module/sideEffects metadata. |
| packages/concerto-vocabulary/package.json | Adds ESM build step + exports/module/sideEffects metadata. |
| packages/concertino/package.json | Adds ESM build step + exports/module/sideEffects metadata. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- e2e: import Page as a type-only import (it is used only as a type), avoiding a runtime named-import mismatch under some TS transpile modes. - build-esm: gate the createRequire shim banner to the Node-only build. Browser-targeted .mjs outputs no longer carry a Node-only `import ... from "module"`, which could break downstream browser bundlers. Verified the browser bundles emit zero runtime require() calls (externals resolve as ESM imports), so the shim was unused there; the node-only package still receives it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk>
The browser-targeted ESM build externalised Node builtins, leaving bare `import "fs"` (concerto-core, concerto-util) and `import "path"` (concerto-util) in dist/esm/index.mjs. These only resolve in downstream consumers that ship Node-polyfill/fallback infrastructure; a stricter browser bundler would fail to resolve them. Stub Node builtins to empty modules for browser builds via an esbuild plugin (requires the async build API), matching the parity the webpack UMD build already achieves via resolve.fallback (fs/path -> false). The node-only linter build still externalises builtins and keeps its createRequire banner. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk>
Decorated is the base class of all decorated model elements (Declaration, Property, etc.) and was previously accessible only via the types/lib/introspect/decorated deep import path. With the exports field added in this PR, that path is no longer reachable. Exporting it from the main entry point is the correct fix. Signed-off-by: Matt Roberts <code@rbrts.uk>
issues.jsonl is a local beads issue-tracker data file that was accidentally committed. Remove it and ignore it so it never re-appears in diffs. This fixes the license-check CI failure (the tool scanned the file and found no Apache 2.0 header). Signed-off-by: Matt Roberts <code@rbrts.uk>
4f3e6ba to
cab5fc7
Compare
The exports field added for tree-shaking encapsulated each package to ./dist/* + ./package.json, which silently made the published ./types/* declaration tree (shipped outside dist/) unreachable under node16/nodenext and bundler resolution — a resolution regression for any consumer deep- importing those supplemental .d.ts paths, which resolved fine before the exports field existed. Map ./types/* alongside ./dist/* on the four packages that publish a types/ tree (util, cto, core, vocabulary) so the pre-existing deep-import surface is preserved. Verified with a node16-resolution tsc probe that a types/ deep-import now resolves (TS2307 before -> clean after). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk>
The ESM dayjs-setup output lived at dist/esm/dayjs-setup.js. Since the package is not "type": "module", Node parses a .js file as CommonJS, so an ESM file with that extension is ambiguous. Emit it as .mjs and point the sideEffects entry at the .mjs path so the dayjs.extend() side effect stays correctly declared. Also document in DEVELOPERS.md that the monorepo must be built in dependency order (npm run build), because each package's exports.import now resolves to dist/esm/index.mjs. Addresses review feedback on PR #1263. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk>
….0.0) (#1306) * feat(concerto): add tree-shakeable package entrypoints Signed-off-by: Rishabh Jain <rishabhj2005@email.com> * fix(concerto-core): remove ESM entrypoint from sideEffects to enable package-level tree shaking Listing `./dist/esm/index.mjs` in sideEffects prevented bundlers from skipping concerto-core entirely when nothing from it is imported. Instead, emit `dist/esm/dayjs-setup.js` as a separate file and reference that in sideEffects — keeping the real side effect (dayjs.extend() calls) declared while allowing the main ESM bundle to be tree-shaken at the package boundary. Verified: importing only concerto-util produces a 59 KB bundle; adding concerto-core jumps to 1.46 MB, confirming the package is correctly excluded when unused. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(concerto-core): emit dayjs-setup as .mjs and document build order The ESM dayjs-setup output lived at dist/esm/dayjs-setup.js. Since the package is not "type": "module", Node parses a .js file as CommonJS, so an ESM file with that extension is ambiguous. Emit it as .mjs and point the sideEffects entry at the .mjs path so the dayjs.extend() side effect stays correctly declared. Also document in DEVELOPERS.md that the monorepo must be built in dependency order (npm run build), because each package's exports.import now resolves to dist/esm/index.mjs. Addresses review feedback on PR #1263. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(concerto): address Copilot review on ESM tree-shaking PR - e2e: import Page as a type-only import (it is used only as a type), avoiding a runtime named-import mismatch under some TS transpile modes. - build-esm: gate the createRequire shim banner to the Node-only build. Browser-targeted .mjs outputs no longer carry a Node-only `import ... from "module"`, which could break downstream browser bundlers. Verified the browser bundles emit zero runtime require() calls (externals resolve as ESM imports), so the shim was unused there; the node-only package still receives it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(concerto): stub Node builtins in browser ESM instead of bare imports The browser-targeted ESM build externalised Node builtins, leaving bare `import "fs"` (concerto-core, concerto-util) and `import "path"` (concerto-util) in dist/esm/index.mjs. These only resolve in downstream consumers that ship Node-polyfill/fallback infrastructure; a stricter browser bundler would fail to resolve them. Stub Node builtins to empty modules for browser builds via an esbuild plugin (requires the async build API), matching the parity the webpack UMD build already achieves via resolve.fallback (fs/path -> false). The node-only linter build still externalises builtins and keeps its createRequire banner. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(concerto-core): export Decorated from public API Decorated is the base class of all decorated model elements (Declaration, Property, etc.) and was previously accessible only via the types/lib/introspect/decorated deep import path. With the exports field added in this PR, that path is no longer reachable. Exporting it from the main entry point is the correct fix. Signed-off-by: Matt Roberts <code@rbrts.uk> * chore: remove stray issues.jsonl and add to .gitignore issues.jsonl is a local beads issue-tracker data file that was accidentally committed. Remove it and ignore it so it never re-appears in diffs. This fixes the license-check CI failure (the tool scanned the file and found no Apache 2.0 header). Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto-core): ESM pilot — modelfile.ts + securityexception.ts (locks recipe R1-R10) Pilot for #1304 (concerto-334). Migrates two exemplar files to native ESM: - securityexception.ts: leaf, external named import (R3) + dual export (R1) - modelfile.ts: requires->imports (R2), global-undefined block->import type (R7), export=->dual export (R1), field declarations for subclass type-debt (R10) Locks the transformation recipe. Confirms: tsc-green is incremental per-file (bucket-A field-decls self-checkable); migrated<->unmigrated seam errors (bucket-B: TS2709/2351/2554) self-resolve at completeness. Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto-core): native ESM migration — model batch (#1304) Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto-core): native ESM migration — serializer batch (#1304) Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto-core): native ESM migration — introspect-b batch (#1304) Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto-util): native ESM migration — util batch (#1304) Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto-core): native ESM migration — introspect-a batch (#1304) Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto-core): native ESM migration — core-root batch (#1304) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(esm): resolve integration seam type errors after native-ESM migration Phase C integration fixes for #1304. After migrating concerto-util and concerto-core CJS-interop syntax to native ESM, workspace imports resolve to their real types instead of `any` (previously masked by `const X = require(...)`). This unmasked pre-existing latent type inconsistencies at the migrated<->unmigrated seams. All fixes are runtime-neutral (verified against the 455c779 baseline, which had 0 tsc errors); no existing test files are modified. - validationexception: `component?` (JSDoc already says optional; extends BaseException whose 2nd/3rd params are optional) — clears 20 TS2554 - jsonpopulator: `visit(thing: any)` — the Declaration|Field union does not share the duck-typed decl/field predicates called via `?.()`; `path?: TypedStack<string>` matches the value always assigned at runtime - resourcevalidator: `constructor(options?)` — body already does `options || {}`; called with 0 args from factory.ts - metamodel: drop dead trailing `true` 5th arg to ModelFile ctor (ctor has 4 params and never reads arguments[4]; baseline tolerated it only because `ModelFile` was `require(...)` = any) - modelfile.getImports: annotate `result: string[]` (was inferred never[]) - jsongenerator: `let id: any = null` (matches sibling `result: any`) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(esm): use namespace import for uuid in factory (no ESM default export) The migration converted `const uuid = require('uuid')` to `import uuid from 'uuid'`, but uuid v9+'s ESM build exposes only named exports (v4, etc.) with no default. tsc's esModuleInterop synthesized a default (so the CJS build and .d.ts emit succeeded), but the esbuild ESM bundle (build:esm) failed to resolve `default`. Usage is `uuid.v4()`, so `import * as uuid from 'uuid'` is the correct, runtime-neutral form and resolves cleanly under both tsc (CJS interop) and esbuild (native ESM). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * docs(esm): add #1304 plan + cross-session handoff Captures the strategic fork (Options A hybrid / B v5 clean-break / C measure-first), Phase-C implementation state, gating measurements, and resume instructions. Branch is a resumable checkpoint pending a human release-strategy decision. Refs: concerto-3oj, concerto-334 Signed-off-by: Matt Roberts <code@rbrts.uk> * test(esm): migrate deep source requires to named exports (#1304) Option B (clean break, v5) resolves the constraint conflict recorded in plan-issue-1304-esm-migration.md §4: with leaf modules on native ESM, `export default X` compiles to `exports.default = X` under `module: commonjs`, so the existing `const X = require('../src/x'); new X()` pattern in the mocha suites throws "X is not a constructor". Under a major release those source-coupled requires are updated rather than reverted. Each deep require now destructures the module's named export (`const { X } = require('../src/x')`), falling back to `.default` where the local binding does not match a named export. - concerto-util: 85 passing / 66 failing -> 151 passing / 0 failing - concerto-core: 93 passing / 279 failing -> 1276 passing / 0 failing No source or public API changes; test wiring only. Also appends the required licence header to the plan document so `license-check-and-add` passes. Refs #1304 Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto-cto,concerto-vocabulary): native ESM migration (#1304) Completes the Option B clean break across the published surface. These were the last two packages still on TypeScript's CJS-interop syntax; concerto-core and concerto-util were migrated earlier on this branch, and concerto-analysis, concertino and concerto-linter were already clean. concerto-cto: - `export = Class` -> `export { Class }; export default Class;` - `export = { a, b }` -> individual named exports plus a default object of the same shape, so `Parser`, `Printer` and `External` keep their runtime shape while their members become individually tree-shakeable. - `import X = require('./x')` -> `import X from './x'`, except the generated peggy parser, which has no default export and uses `import * as Parser`. - `parseexception.ts` drops a `// @ts-ignore`d `require` for a real import. concerto-vocabulary: - `export = Class` -> named + default exports. - The vocabulary <-> vocabularymanager cycle is removed at the source: the type-only direction becomes `import type`, which erases at compile time, so the compiled module graph has no cycle at all. Public API surface is unchanged in both packages: the barrels export the same names with the same runtime shapes. Test counts match baseline exactly (cto 163, vocabulary 89). Refs #1304 Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(build): emit ESM as a module graph so packages actually tree-shake Native ESM source syntax is a prerequisite for tree-shaking, not a sufficient condition. The ESM build was flattening each package into a single dist/esm/index.mjs, and once every module is inlined into one file there is nothing left for `sideEffects` to act on: a consumer's bundler is reduced to statement-level DCE across one large file, which the packages' cross-references defeat immediately. Measured before this change, importing `SecurityException` from concerto-core - a two-line exception subclass - cost 544,356 B against a 559,367 B whole-package ceiling. 97% of the package survived elimination. Make every src/**/*.ts module an entry point and emit with outdir + splitting + `.mjs` output extension, so the ESM build mirrors what tsc already produces for CJS: one output module per source module, shared code hoisted into chunks. dist/esm/index.mjs keeps its path, so main/module/exports are untouched. Minified browser-bundle sizes, before -> after: concerto-core, SecurityException only 544,356 B -> 3,627 B (-99.3%) concerto-core, ModelManager only 552,634 B -> 418,282 B (-24.3%) concerto-core, whole package 559,367 B -> 547,863 B concerto-util, Writer only 17,215 B -> 739 B (-95.7%) concerto-util, whole package 22,253 B -> 22,322 B Whole-package imports are unchanged, as expected; the win is in what a consumer does not import. ModelManager legitimately reaches most of the package, so its 24% is the honest floor for that symbol. Verified: all seven packages emit index.mjs plus a per-module graph; a Node ESM smoke test exercises ModelManager/Factory/Serializer round-tripping, CTO parse and print, Writer, TypedStack and VocabularyManager against the emitted .mjs; and a minified, tree-shaken consumer bundle that never imports dayjs-setup explicitly still round-trips a DateTime with the utc plugin live, confirming the one genuine module-level side effect in the tree survives shaking. Refs #1304 Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * docs(esm): add MIGRATION.md for v5 and record the Option B decision MIGRATION.md is the consumer-facing guide for the 5.0.0 clean break: what breaks (deep ./dist/* constructor imports, in both CJS and ESM form), what does not (every root-package import), how to fix each, and the measured tree-shaking numbers. It also documents the type-import position: the packages deliberately do not widen their `exports` map to re-expose the `types/` declaration tree. Consumers should use `import type` from the package root, which is erased at compile time, cannot anchor a module into a bundle, and resolves identically under every module-resolution mode. Any type not reachable from a root barrel should be added to that barrel rather than deep-imported. The plan document records the Option B decision, the execution log, and the tree-shaking measurement including the two hypotheses that were tested and rejected before the real root cause was found. Refs #1304 Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(concerto-core): restore \u200C/\u200D escapes in ID_REGEX The ESM migration replaced the escaped zero-width non-joiner and zero-width joiner in ID_REGEX with the literal characters. They are invisible in a diff, easy to corrupt through copy/paste or editor normalisation, and inconsistent with the sibling regex in concerto-util's identifiers.ts, which kept the escapes. Matching behaviour is unchanged. Reported by Copilot on #1306. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(build): emit separate node and browser ESM builds The ESM build stubbed Node builtins to empty modules for every non-linter package, which is correct for a browser bundle and wrong for Node. Since the `exports` map pointed the `import` condition at that build, Node ESM consumers silently received stubs: `new FileWriter(dir)` threw "fs.mkdirSync is not a function", and ModelWriter and ModelLoader failed the same way — at runtime, not at build time. Emit two ESM builds instead. dist/esm is node-targeted and keeps builtins external, so `import` resolves to real fs/path. dist/esm-browser keeps the stubbing and is routed through a new `browser` export condition, placed before `import` so a browser bundler matches it first. Node-only packages get just the node build. Adding the `browser` condition means webpack now resolves sibling workspace packages to their ESM build when producing the UMD bundles. Webpack treats .mjs as fully specified, which breaks the extensionless request its `process` ProvidePlugin injects, so the three UMD configs get a .mjs rule turning that off; the sibling packages' own relative imports already carry extensions. concerto-core's sideEffects now also lists the browser copy of dayjs-setup, so the plugin registration survives shaking on both builds. Verified: ModelWriter, FileWriter and ModelLoader all work through the node ESM entry; the browser build still carries no bare builtin imports; tree-shaking is unchanged on both (browser SecurityException 3,666 B against a 547,984 B ceiling, Writer 739 B); full suite and the UMD browser e2e tests pass. Reported by Copilot on #1306. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(build): bind process in the browser ESM build 3cb7b87 routes browser bundlers to dist/esm-browser through a new `browser` condition. That graph leaves `process` free — the serializer reads `process.env.TZ`, warning.ts reads `process.emitWarning`, bundled deps read `process.env.NODE_ENV` — which used to be someone else's problem only inside this repo, where the three UMD configs answer it with ProvidePlugin. Now it is shipped, and it breaks downstream webpack consumers: ProvidePlugin's extensionless `process/browser` request is rejected as not fully specified once the importing module is .mjs. accordproject/template-engine reproduces it — `npm run webpack` (part of its `build:dist` and `prepublishOnly`) fails to build: ERROR in ./node_modules/@accordproject/concerto-util/dist/esm-browser/chunk-GG6UL5GV.mjs Module not found: Error: Can't resolve 'process/browser' BREAKING CHANGE: ... resolved as fully specified Its config aliases concerto-core to the UMD bundle but not concerto-util, so concerto-util resolves through the new condition. The `.mjs` fullySpecified rule added to this repo's webpack configs fixes it here and cannot reach a consumer's config. Inject a process shim into the browser build instead, so the graph is self-contained and no consumer needs a polyfill or a resolver rule. It defers to a real `globalThis.process` when the page has one, so an existing consumer polyfill still wins; the fallback covers only what these packages read. Verified: template-engine's webpack bundle builds again (0 errors) and its 109 tests pass; concerto-playground builds and passes 328 unit + 104 e2e; this repo's suite and the 3 UMD browser e2e tests are unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D2DzEd3mZB2jyJqpk6Bn6T Signed-off-by: Claude <noreply@anthropic.com> * test(esm): add a Node ESM smoke test and run it in CI Every unit suite executes against src/ through ts-node, so nothing in the repo exercises the emitted ESM. That is why serving the stubbed browser graph to Node went unnoticed until Copilot read the build script, and why a free `process` in the browser graph shows up only in a downstream consumer's bundler. The smoke test imports each package the way a consumer does and asserts the fs-backed APIs actually touch disk, that ESM and CJS expose the same names, and that the browser graph leaves no unbound `process`. Both regressions fail it; the fixes pass it. Wired into build.yml after the unit tests. Adds `mjs` to the root license-check format list so the new script's header is checked with the same comment style as `.js`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D2DzEd3mZB2jyJqpk6Bn6T Signed-off-by: Claude <noreply@anthropic.com> * docs(esm): document the two ESM graphs and the dual-package hazard The exports-map reference still showed the single-graph shape from before 3cb7b87. It now shows the `browser` condition and says which graph a given runtime or bundler selects — nothing in consumer code chooses between them. The dual-package hazard gets its own section under breaking changes. In 4.x a package had no exports map and no module field, so `import` and `require` landed on the same CommonJS file and a process held one copy. From 5.0.0 they resolve to different files, so a process that reaches a package both ways holds two sets of class identities and concerto's `instanceof` guards start rejecting objects that are obviously the right type: Error: "Serializer.toJSON" only accepts "Concept", "Event", "Asset", "Participant" or "Transaction". This is inherent to shipping both module systems rather than something to fix in the build, so the section says how to avoid loading a package twice and how to recognise it when it happens. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D2DzEd3mZB2jyJqpk6Bn6T Signed-off-by: Claude <noreply@anthropic.com> * docs(esm): drop the #1304 planning document from the repo plan-issue-1304-esm-migration.md was a cross-session handoff artifact — it described itself as a resumable checkpoint and existed to carry WIP state between working sessions while the migration was paused on the Option A/B/C decision. That decision is made and the work is finished, so it is process scaffolding rather than repository content. Nothing references it. What is worth keeping has a better home: MIGRATION.md carries the consumer-facing guidance, and the rationale, measurements and rejected hypotheses are recorded in the pull request. It also had to carry an appended licence header purely to satisfy license-check-and-add, which is a sign it did not belong at the repo root. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * fix(build): keep runtime dependencies external in the node ESM build The ESM build marked only workspace packages as external, so every runtime dependency was compiled into the output. tsc does the opposite for the CJS build, emitting require("dayjs"), which meant the two published artifacts disagreed about what a dependency is. Bundling gave each package its own private copy: debug was compiled into concerto-util, concerto-core and concerto-cto independently, and an application depending on all three shipped three copies and deduplicated none. It also hid those dependencies from npm audit and SBOM tooling, and made a patch to any of them require republishing concerto rather than a lockfile bump. Published dist/esm, .mjs bytes: concerto-util 75,726 -> 40,887 -46% concerto-core 958,029 -> 441,228 -54% concerto-vocabulary 349,284 -> 87,639 -75% concerto-cto 505,039 -> 491,738 -3% total 1,888,078 -> 1,061,492 -44% Consumer bundle sizes barely move (-0.3% to -0.8%): the remaining duplication is @accordproject/concerto-metamodel, which has to stay bundled — see below — and it dominates what the packages share. The win here is the published artifact and dependency hygiene, not the consumer's bundle. The browser build still bundles its dependencies and its output is unchanged byte-for-byte. It is consumed as a self-contained graph, and its Node-builtin stubbing only holds if the dependencies reaching for builtins are resolved here rather than by the consumer. Four dependencies stay bundled because they are CommonJS with no ESM build and Node's cjs-module-lexer cannot see their named exports; externalising them emits `import { MetaModelUtil } from '...'` and Node throws "Named export not found" at load time. The exception list carries the command to re-test them. Two source imports needed file extensions. dayjs and @stoplight/spectral-cli publish no exports map, so Node ESM rejects an extensionless subpath: bundling had been resolving `dayjs/plugin/utc` by extension inference, and once the specifier survives into the output it has to be `dayjs/plugin/utc.js`. Both forms work unchanged under CommonJS. Verified: npm run test:esm 10/10 (it caught both failures above before they could ship), full monorepo suite unchanged, UMD browser e2e 3/3, lint and licchk clean, dist/esm-browser byte-identical. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * build: run the ESM smoke test as part of the build The smoke test exercises the emitted ESM rather than src/, so it only ran as a separate CI step. That left the feedback loop backwards: both regressions it has caught came from editing scripts/build-esm.js, and the contributor editing that file got a clean `npm run build` locally and learned about the breakage from CI minutes later. Hooking it to postbuild puts the check where the failure is: a build that emits a package which cannot be imported has failed. It also gates publishing for free, since publish.yml runs `npm run build` before `npm publish`. It has to hang off the root build, not an individual package's. The script imports all four packages by name, so it needs the full ordered build to have finished; a postbuild on concerto-util would fire during build:level0, before core and cto exist. The dedicated CI step is now redundant and removed — it would otherwise run twice on each of the six matrix legs, plus again in the e2e job, which builds through pretest:e2e. Verified the guard actually bites: reintroducing the extensionless `dayjs/plugin/utc` import makes `npm run build` exit 1 rather than emitting a broken artifact. Costs 1.7s against a 51s ordered build. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * feat(concerto)!: drop the UMD browser bundles The webpack UMD builds are removed from concerto-core, concerto-util and concerto-cto, along with the legacy top-level `browser` field that pointed at them. The `exports` map introduced for tree-shaking had already demoted them: it is consulted before the legacy `browser` field, so webpack 5, Vite, Rollup and esbuild were resolving the root import to dist/esm-browser rather than the UMD bundle. That was measurable downstream — concerto-playground's production bundle dropped 14% on this branch precisely because Vite stopped using the UMD build. What remained was a ~1MB artifact serving `<script src>` users and tooling too old to read `exports`. Removing it takes roughly a third off the ordered build (concerto-core's webpack step alone was 13.8s of ~51s) and drops webpack, webpack-cli, babel-loader, @babel/preset-env, node-polyfill-webpack-plugin and process from devDependencies — 241 packages out of the lockfile. The four .babelrc files go with them: they existed only to feed babel-loader inside the deleted webpack configs, and left in place would have pointed at an uninstalled preset. concerto-vocabulary's was already dead. The `browser` *condition* inside each `exports` map is untouched. That is the supported browser entry point and is what bundlers already use. The browser e2e tests are rewritten against the ESM graph rather than deleted, which closes a real gap: dist/esm-browser is the artifact browser consumers now receive and nothing tested it in a browser. Doing so needed two things the UMD tests never did. A module graph cannot be injected with addScriptTag — it imports sibling chunks by relative path — so the suite serves each package's dist/esm-browser over HTTP and imports it. And concerto-core's graph imports @accordproject/concerto-cto and -util as bare specifiers, which a browser cannot resolve, so the page carries an import map. Navigating to about:blank first, as the UMD suite did, fails: Chromium's Private Network Access check blocks a null-origin page from fetching loopback, so the server also serves a same-origin document to land on. Also adds e2e/.eslintrc.yml. That directory had no working TypeScript ESLint setup — `npx eslint .` failed to parse even the pre-existing spec — and it now holds two TypeScript files worth linting. Scoped with `root: true`. BREAKING CHANGE: the UMD bundles dist/concerto-core.js, dist/concerto-util.js and dist/concerto-cto.js are no longer published, and the `window['concerto-core']` style globals they exposed are gone. Bundler users are unaffected. `<script src>` users need a bundler or a module-type script; MIGRATION.md documents both. Verified: build clean with the ESM smoke test passing, full suite unchanged (1276/163/151/89/99/18/19), browser e2e 3/3 against the ESM graph, lint clean across all four changed areas, licchk clean, and no dist/concerto-*.js emitted. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * docs(esm): correct the browser-resolution notes for the UMD removal Two inaccuracies, both introduced by describing the browser story before the UMD bundles were actually removed. The bundler-user note explained that nothing changes for them "because exports takes precedence over the legacy browser field". That framing describes a conflict that no longer exists: the legacy browser field is gone. Reworded to say what is now true — those tools read exports, so they had already stopped using the UMD bundle, and removing it takes away something they were not resolving to. More substantially, the document listed only bundler users and script-tag users as affected. It missed the group that actually gets the worst of this: tooling that does not read exports at all. webpack 4, browserify and Parcel 1 found the UMD bundle through the top-level browser field, and with both that field and the bundle removed they now fall back to main — the CommonJS build, which imports fs and will not run in a browser. That failure is real and surfaces as a confusing missing-module error, so it is now called out explicitly, along with the fact that there is no supported path for those tools in 5.0.0. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <code@rbrts.uk> * build: externalise concerto-metamodel now that 3.17.0 is lexable concerto-metamodel was the one runtime dependency held back from the Node ESM build's externalisation list. Its CommonJS entry point assigned exports with a string-literal object value, which halts cjs-module-lexer's scan, so Node could not see the named exports and `import { MetaModelUtil } from '@accordproject/concerto-metamodel'` threw at load time. Bundling it was the workaround. 3.17.0 carries the upstream fix, so the workaround can go: parse(index.js).exports -> [ 'MetaModelUtil', 'MetaModelNamespace', 'DcsCto', 'DcsNamespace' ] Raise the dependency floor to ^3.17.0 in the five packages that depend on it. The floor is load-bearing rather than cosmetic: under ^3.16.0 npm could resolve a version without the fix and the Node ESM build would break at runtime. Published artefacts shrink by the copies they no longer carry: concerto-core 441,228 -> 374,081 bytes (-15%) concerto-vocabulary 87,639 -> 25,408 bytes (-71%) Bundled consumers see much less than that (a four-package bundle goes 587,881 -> 585,417, -0.4%): esbuild was already tree-shaking the inlined copies down to the parts actually reached, and a single external CommonJS copy cannot be tree-shaken, which offsets most of the deduplication. The win here is install and download size, unbundled Node consumers, and having one metamodel version in the tree instead of four. The three @stoplight/spectral-* packages remain bundled; their named exports are still invisible to the lexer. Signed-off-by: Matt Roberts <code@rbrts.uk> * docs(esm): re-measure the tree-shaking table under one consistent method The published table mixed measurement methods: the 4.x column bundled a package's `dist/index.js` directly while the 5.0.0 column resolved through the `exports` map, and the numbers had drifted from the build as later commits landed. Re-measure both columns identically — import by package name, so resolution happens the way it does in a consumer's project — and give the browser and Node targets their own rows, since they resolve to different artefacts on both sides. 4.2.0 ships no `exports` map, so a browser bundler takes its `browser` field, which is the UMD bundle; that is what browser consumers actually got, and it is why the browser column starts so much higher than the Node one. Signed-off-by: Matt Roberts <code@rbrts.uk> * refactor(types)!: tighten introspect and model types, drop redeclared fields (#1308) * refactor(types)!: tighten introspect and model types, drop redeclared fields The ESM migration replaced `require()` with `import`, which restored real base-class types across `concerto-core` and so switched property checking back on. The migration papered over the resulting errors by declaring every instance field as `: any`, including fields that the base class already declared. This replaces those with real types. Declared once, in the owning class ---------------------------------- - ClassDeclaration no longer redeclares `modelFile` (Declaration owns it). - MapDeclaration no longer redeclares `modelFile`, `name` or `fqn`, and drops its `getModelFile`/`getName`/`getFullyQualifiedName` overrides, which were byte-identical to Declaration's. Its `process()` no longer recomputes `name`/`fqn` that `super.process()` has already set. - Property dropped `modelFile`, which was declared but never assigned. - ModelFile dropped `modelFile` and `ast`, likewise never assigned and already owned by Decorated. Fields carry definite assignment assertions rather than initialisers throughout: these classes are populated by a `process()` method that a base constructor invokes, and with `useDefineForClassFields` off a subclass initialiser is emitted after that constructor has run, clobbering the value. Real types ---------- - `Decorated.ast` is now an exported `AstNode` interface, and `decorators` is `Decorator[]`. `getModelFile()` declares `ModelFile`, which removes the casts its callers needed. - Declaration, ClassDeclaration, ScalarDeclaration, MapDeclaration, MapKeyType, MapValueType, Property, Field, RelationshipDeclaration, Decorator, ModelFile, Introspector and the four Validators carry concrete field and return types; nullable fields are `T | null` rather than `any`. - `ModelFile.getDeclarations()` is generic, so `getAssetDeclarations()` and friends return their own declaration type. - `NullUtil.isNull` and `ModelUtil.isValidIdentifier` are type predicates, which narrows at their call sites instead of forcing casts. - BaseModelManager, Factory, Serializer, the serializer visitors, the model classes, DecoratorManager and DecoratorExtractor take concrete field types. New shared interfaces live in `types.ts`: `SerializerOptions`, `GenerateOptions`, `InstanceGeneratorParameters`, and the decorator command shapes mirroring the DCS model. - `concerto-util` exports `WritableModelFile`/`WriteModelsOptions`; `concerto-cto` types `parse()` as `IModel`, gives `resolveExternal` a named options type, and drops the `as any` casts in FileDownloader. Bugs the tightening surfaced ---------------------------- - Property and ModelFile passed an always-undefined `this.modelFile` to IllegalModelException; they now pass the real ModelFile. - ScalarDeclaration passed `this.ast.name.location` as the *modelFile* argument to IllegalModelException, which was always undefined; it now passes `this.modelFile` and `this.ast.location`. - ClassDeclaration.declarationKind() gained a `return ''` stub during the migration, silently answering with an empty string for any subclass that forgot to override it. It throws now, matching Decorated.getModelFile(). Downstream, concerto-analysis and concerto-vocabulary needed null guards and narrowing casts where core methods now admit null. Breaking: the emitted .d.ts files change shape. Runtime behaviour is unchanged apart from the three exception arguments noted above. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YAZpnt3uqfBeGWeKAcwHXS Signed-off-by: Matt Roberts <code@rbrts.uk> * refactor(types): address review, narrow validator ASTs to metamodel types - CollectionSizeValidator, NumberValidator and StringValidator take their real metamodel nodes (ICollectionSizeValidator, the three domain validators, IStringRegexValidator/IStringLengthValidator) instead of the generic AstNode. Validator.validator is a union of those, and each subclass narrows it with `declare`, which emits nothing. - Property.decorator is gone. It was only ever assigned null and never read in src or test. - Decorator.handleError takes `string | Error` rather than `unknown`: the in-validate callers pass a message they just built, the catch passes the exception. - Identifiable.$timestamp is `Dayjs`, not `any`, and the JSDoc on it and on the Identifiable/Resource/Relationship constructors says so. It was documented as a string but has always held a Dayjs, which is what JSONGenerator formats and JSONPopulator rebuilds. - DecoratorExtractor keeps the explicit `> 0` comparison, via `?? 0`, rather than relying on a falsy length. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YAZpnt3uqfBeGWeKAcwHXS Signed-off-by: Matt Roberts <code@rbrts.uk> --------- Signed-off-by: Matt Roberts <code@rbrts.uk> Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Matt Roberts <7544022+mttrbrts@users.noreply.github.com> * fix(esm): address type-safety review comments on PR #1306 jamieshorten's review flagged several `as unknown as` / `as X[]` casts that the native-ESM migration introduced once real types replaced the old CJS-interop `any`s. - concerto-vocabulary/vocabulary.ts: getAllDeclarations() returns Declaration[], and the only member used here is getName(), so drop the unnecessary ClassDeclaration cast in favour of the real type. - concerto-analysis/compare.ts: getAllDeclarations() is cast to ClassDeclaration[] so map/scalar declarations can flow through the same comparer pipeline. Verified runtime-safe (compareClassDeclaration guards with instanceof, and the public Comparer.compareClassDeclaration callback already has to tolerate this), so this is documented with a SAFETY comment rather than widened, since a type-level fix would mean changing the public Comparer callback's parameter type. - concerto-core/basemodelmanager.ts: the two ModelWriter/FileDownloader casts are similarly runtime-safe (ModelFileLoader always supplies fileName/definitions; both ModelFileInstance and ModelFileSource only need to structurally satisfy `{ ast }`) but not provable by their current public interfaces, so both get a SAFETY comment explaining why. No behaviour change. Full build (tsc + ESM emit + smoke test), lint and the affected packages' unit tests (concerto-core 1278, concerto-analysis 99, concerto-vocabulary 89) all pass unchanged. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ECqBEJBSn19CRhCHLFmEw9 Signed-off-by: Claude <noreply@anthropic.com> * refactor(types)!: fix the signatures the casts were hiding Follow-up to the review on #1306. The three `as unknown as` / `as X[]` casts were documented with SAFETY comments in a6a5688 on the grounds that removing them meant changing public API. Since 5.0.0 is a breaking release, change the API instead: each cast existed because a signature did not describe what the code actually does. FileDownloader<TFile, TSeed = TFile> ------------------------------------ One type parameter served as both the input and the output of downloadExternalDependencies(), but the files seeding the walk are not the type the bound FileLoader produces: BaseModelManager seeds it with parsed ModelFile instances and gets back raw ModelFileSource objects. The old signature could only be satisfied by casting to `ModelFileInstance[] & ModelFileSource[]` — an intersection no element can actually be. TSeed names the seed type and defaults to TFile, so existing single-parameter uses are unaffected; getExternalImports takes `TFile | TSeed`, which is exactly what it is handed at runtime. Comparer.compareClassDeclaration takes a Declaration ---------------------------------------------------- Every declaration in a model file goes through this callback, map and scalar declarations included, so `getAllDeclarations() as ClassDeclaration[]` was asserting something false to satisfy a callback type that had always been narrower than reality. Widening it to Declaration makes the compiler enforce what the runtime already required: narrow before reaching for ClassDeclaration members. The built-in comparers needed no changes — they only call Declaration-level methods and getDeclarationType(), which already took a Declaration. compareClassDeclaration()'s two negative instanceof guards collapse into one positive `instanceof ClassDeclaration` check: ScalarDeclaration and MapDeclaration both extend Declaration directly, so the positive form covers them and any future declaration kind, rather than needing a new guard per kind. writeModelsToFileSystem narrows instead of casting -------------------------------------------------- WritableModelFile requires a fileName and definitions; ModelFile types both nullable because a model file built from an AST alone has neither. That is real information, not noise, so the call site now narrows and throws an error naming the namespace it cannot write, rather than casting and letting fs raise a TypeError several frames later. Managers loaded from CTO are unaffected. MIGRATION.md documents all three under breaking changes. Verified: full build (tsc, both ESM graphs, 10/10 ESM smoke checks), full suite unchanged (concerto-core 1278, concerto-cto 163, concerto-util 151, vocabulary 89, analysis 99, plus the jest suites), lint and licence checks clean. No runtime behaviour change apart from the writeModelsToFileSystem error message. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ECqBEJBSn19CRhCHLFmEw9 Signed-off-by: Claude <noreply@anthropic.com> --------- Signed-off-by: Rishabh Jain <rishabhj2005@email.com> Signed-off-by: Matt Roberts <code@rbrts.uk> Signed-off-by: Claude <noreply@anthropic.com> Signed-off-by: Matt Roberts <7544022+mttrbrts@users.noreply.github.com> Co-authored-by: Rishabh Jain <rishabhj2005@email.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
|
This PR is stale because it has been open with no activity. Remove the stale label or comment to keep it active. Only items with maintainer engagement are auto-closed. |
Closes #1261.
Makes the 7 published
@accordproject/*packages tree-shakeable in web bundles, without breaking existing consumers: additive ESM output alongside the existing CJS/UMD, conditionalexports,sideEffectsnarrowed to the real side effect, and thedayjs.extend()calls consolidated into one module.Rebased on current
main(was 10 behind) and re-verified end-to-end. Rishabh's original commits and DCO sign-offs are preserved.What changed
sideEffectson every package — narrowed to just the module that has a real load-time side effect. Inconcerto-corethat isdayjs-setup(thedayjs.extend()calls for UTC / quarterOfYear / duration / minMax), emitted as a standalone file so the main ESM bundle stays fully tree-shakeable at the package boundary.exports—import→dist/esm/index.mjs,require→dist/index.js,types→dist/index.d.ts. The"./dist/*"escape hatch is kept so existing deep-import consumers keep resolving (non-breaking over encapsulation for this PR).dist/esm/index.mjsper package; existing CJS (dist/index.js) and UMD (dist/concerto-*.js) outputs are unchanged.dayjs-setupemitted as.mjs(not.js) — the package is not"type": "module", so a.jsfile containing ESM is parsed as CJS by Node and is ambiguous.sideEffectspoints at./dist/esm/dayjs-setup.mjsin lockstep.npm run build), because each package'sexports.importresolves to itsdist/esm/index.mjs.Verification (all green on the rebased branch)
concerto-coreemitsdist/esm/dayjs-setup.mjsModelManagerimport → 579 KB (minified) pulling core in as expectedrequire, ESMimport, deepdist/*import, andnode16/nodenexttype resolution all work. The onlytscerrors are 5 pre-existing TS8023 JSDoc errors also present on published 4.2.0 — zero new errorsfromJSON/toJSONround-trip + UTC plugin active in both CJS and ESM consumption paths — the tree-shaker does not dropdayjs-setupKnown limitation (tracked as follow-up)
Per-export tree-shaking inside
concerto-coredoes not work yet — importing 1 export vs all differs by ~0.14%. Root cause: the ESM build isbundle: true, producing a CJS-in-ESM blob, forced because 58/59concerto-core/srcfiles use TypeScriptexport =/import X = require()(illegal as native ESM, TS1203).A throwaway spike migrating one leaf module (
securityexception.ts) to native ESM withbundle: falsemeasured 595,862 B → 22,908 B for a single export (96.2% reduction), confirming the win is real. Full migration ofconcerto-core(+concerto-util) is a mechanical, bottom-up ~3–5 dev-day effort, tracked as a follow-up epic — out of scope for this PR so the "tests pass unchanged" guarantee is never at risk.Scope
./dist/*escape hatch — deliberately not done (would break deep-import consumers).