From 26450913b70bd80a8e52a15943ac4e01ac4ac520 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=91=D0=BE=D1=80=D0=BE=D0=B2=D1=81=D0=BA=D0=B8=D0=B9=20?= =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9?= Date: Tue, 17 Nov 2026 13:28:30 +0300 Subject: [PATCH] feat(modules): generate type contracts --- .changeset/module-contracts.md | 7 + packages/arui-scripts-modules/README.md | 8 + .../src/module-loader/create-lazy-mounter.tsx | 5 +- .../create-typed-module-loader.ts | 18 ++ .../module-loader/execute-module-factory.ts | 9 +- .../module-loader/hooks/use-module-factory.ts | 9 +- .../module-loader/hooks/use-module-mounter.ts | 3 +- .../src/module-loader/index.ts | 2 + .../src/module-loader/module-contract.ts | 39 +++ .../src/module-loader/module-session.ts | 9 +- .../src/module-loader/module-types.ts | 4 +- .../utils/unwrap-default-export.ts | 10 +- .../arui-scripts-modules/src/react/index.ts | 4 + packages/arui-scripts/docs/commands.md | 3 + packages/arui-scripts/docs/modules.md | 67 ++++- packages/arui-scripts/docs/settings.md | 2 + packages/arui-scripts/package.json | 1 + .../arui-scripts/src/commands/build/client.ts | 3 + .../module-contracts/__fixtures__/consumer.ts | 40 +++ .../__fixtures__/portable-contract.ts | 158 ++++++++++ .../__tests__/ambient-contracts.tests.ts | 116 +++++++ .../__tests__/build-module-contracts.tests.ts | 282 ++++++++++++++++++ .../__tests__/consumer-contracts.tests.ts | 95 ++++++ .../__tests__/js-contracts.tests.ts | 41 +++ .../__tests__/json-contracts.tests.ts | 101 +++++++ .../__tests__/local-dependencies.tests.ts | 65 ++++ .../__tests__/module-formats.tests.ts | 197 ++++++++++++ .../build-module-contracts.ts | 110 +++++++ .../module-contracts/contract-dependencies.ts | 74 +++++ .../module-contracts/declaration-paths.ts | 76 +++++ .../declaration-references.ts | 169 +++++++++++ .../module-contracts/emit-declarations.ts | 59 ++++ .../module-contracts/generate-declarations.ts | 254 ++++++++++++++++ .../module-contracts/project-typescript.ts | 29 ++ .../__tests__/validate-module-types.tests.ts | 59 ++++ .../src/configs/app-configs/types.ts | 7 + .../configs/app-configs/validate-config.ts | 2 + .../app-configs/validate-module-types.ts | 27 ++ packages/arui-scripts/src/index.ts | 7 +- .../example-modules/arui-scripts.config.ts | 3 + yarn.lock | 1 + 41 files changed, 2153 insertions(+), 22 deletions(-) create mode 100644 .changeset/module-contracts.md create mode 100644 packages/arui-scripts-modules/src/module-loader/create-typed-module-loader.ts create mode 100644 packages/arui-scripts-modules/src/module-loader/module-contract.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__fixtures__/consumer.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__fixtures__/portable-contract.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__tests__/ambient-contracts.tests.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__tests__/build-module-contracts.tests.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__tests__/consumer-contracts.tests.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__tests__/js-contracts.tests.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__tests__/json-contracts.tests.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__tests__/local-dependencies.tests.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/__tests__/module-formats.tests.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/build-module-contracts.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/contract-dependencies.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/declaration-paths.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/declaration-references.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/emit-declarations.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/generate-declarations.ts create mode 100644 packages/arui-scripts/src/commands/util/module-contracts/project-typescript.ts create mode 100644 packages/arui-scripts/src/configs/app-configs/__tests__/validate-module-types.tests.ts create mode 100644 packages/arui-scripts/src/configs/app-configs/validate-module-types.ts diff --git a/.changeset/module-contracts.md b/.changeset/module-contracts.md new file mode 100644 index 00000000..766cf4c5 --- /dev/null +++ b/.changeset/module-contracts.md @@ -0,0 +1,7 @@ +--- +'arui-scripts': minor +'@alfalab/scripts-modules': minor +--- + +Добавлена генерация npm пакета с типами микрофронтов. +Хост-приложение может подключить этот пакет, чтобы typescript проверял имена модулей и параметры запуска. diff --git a/packages/arui-scripts-modules/README.md b/packages/arui-scripts-modules/README.md index 3492deb4..c92d7acf 100644 --- a/packages/arui-scripts-modules/README.md +++ b/packages/arui-scripts-modules/README.md @@ -597,3 +597,11 @@ Boundary автоматически не перехватывает. Для их Очистка React root откладывается до микрозадачи, чтобы хост мог вызывать unmount во время собственного commit. Повторный запуск в том же контейнере до этой очистки сохраняет root, но создаёт новое дерево приложения с новым состоянием. + +## Типы контрактов модулей + +Включите `modules.types` в конфиге микрофронта, чтобы `arui-scripts` создал пакет с картой `ModuleContracts`. +Используйте ее с `createTypedModuleLoader()`: идентификатор модуля определяет тип его экспорта, +а хуки проверяют переданные параметры. `ModuleRunParams` и `ModuleServerState` позволяют получить отдельные типы из контракта модуля или фабрики. + +Пример настройки, публикации и подключения: [генерация пакета контрактов](../arui-scripts/docs/modules.md#генерация-пакета-контрактов). diff --git a/packages/arui-scripts-modules/src/module-loader/create-lazy-mounter.tsx b/packages/arui-scripts-modules/src/module-loader/create-lazy-mounter.tsx index 676a17af..31ee20d8 100644 --- a/packages/arui-scripts-modules/src/module-loader/create-lazy-mounter.tsx +++ b/packages/arui-scripts-modules/src/module-loader/create-lazy-mounter.tsx @@ -1,6 +1,7 @@ import React, { useEffect, useRef } from 'react'; import { useModuleMountTarget } from './hooks/use-module-mount-target'; +import { type ModuleExports } from './module-contract'; import { reportModuleError } from './module-lifecycle'; import { createModuleSession, @@ -19,7 +20,7 @@ type CreateLazyMounterParams< RunParams, ServerState extends BaseModuleState, > = ModuleMounterOptions & { - loader: Loader>; + loader: Loader>>; /** * Параметры, которые будут переданы в загрузчик (и будут переданы на сервер модуля) */ @@ -58,7 +59,7 @@ export function createLazyMounter< } let loadStage: ModuleMounterErrorStage = 'resolve-export'; - let result: LoaderResult>; + let result: LoaderResult>>; try { result = await loader({ diff --git a/packages/arui-scripts-modules/src/module-loader/create-typed-module-loader.ts b/packages/arui-scripts-modules/src/module-loader/create-typed-module-loader.ts new file mode 100644 index 00000000..d1f31799 --- /dev/null +++ b/packages/arui-scripts-modules/src/module-loader/create-typed-module-loader.ts @@ -0,0 +1,18 @@ +import { createModuleLoader, type CreateModuleLoaderParams } from './create-module-loader'; +import { type BaseModuleState } from './types'; + +// typeScript проверяет moduleId по контракту и подставляет тип модуля +export function createTypedModuleLoader() { + return function createLoader< + Id extends Extract, + GetResourcesParams = undefined, + ModuleState extends BaseModuleState = BaseModuleState, + >( + params: Omit< + CreateModuleLoaderParams, + 'moduleId' + > & { moduleId: Id }, + ) { + return createModuleLoader(params); + }; +} diff --git a/packages/arui-scripts-modules/src/module-loader/execute-module-factory.ts b/packages/arui-scripts-modules/src/module-loader/execute-module-factory.ts index e431f3e6..49e3569d 100644 --- a/packages/arui-scripts-modules/src/module-loader/execute-module-factory.ts +++ b/packages/arui-scripts-modules/src/module-loader/execute-module-factory.ts @@ -1,13 +1,20 @@ import { unwrapDefaultExport } from './utils/unwrap-default-export'; +import { type ModuleExports } from './module-contract'; import { type FactoryModule } from './module-types'; import { type BaseModuleState } from './types'; +export type FactoryModuleExports< + Result, + RunParams, + ServerState extends BaseModuleState, +> = ModuleExports>; + export async function executeModuleFactory< ModuleExportType, RunParams = undefined, ServerState extends BaseModuleState = BaseModuleState, >( - module: FactoryModule, + module: FactoryModuleExports, serverState: ServerState, runParams?: RunParams, ): Promise { diff --git a/packages/arui-scripts-modules/src/module-loader/hooks/use-module-factory.ts b/packages/arui-scripts-modules/src/module-loader/hooks/use-module-factory.ts index b3581385..d7fc92dd 100644 --- a/packages/arui-scripts-modules/src/module-loader/hooks/use-module-factory.ts +++ b/packages/arui-scripts-modules/src/module-loader/hooks/use-module-factory.ts @@ -1,7 +1,6 @@ import { useEffect, useRef, useState } from 'react'; -import { executeModuleFactory } from '../execute-module-factory'; -import { type FactoryModule } from '../module-types'; +import { executeModuleFactory, type FactoryModuleExports } from '../execute-module-factory'; import { type BaseModuleState, type Loader } from '../types'; import { type LoadingState } from './types'; @@ -17,7 +16,7 @@ export type UseModuleFactoryParams< /** * Загрузчик модуля */ - loader: Loader>; + loader: Loader>; /** * Параметры, которые будут переданы в загрузчик (и будут переданы на сервер модуля) */ @@ -40,7 +39,7 @@ export type UseModuleFactoryResult = { /** * Экспорт модуля */ - module: ModuleExportType | undefined; + module: Awaited | undefined; }; export function useModuleFactory< @@ -62,7 +61,7 @@ export function useModuleFactory< RunParams >): UseModuleFactoryResult { const [loadingState, setLoadingState] = useState('unknown'); - const [module, setModule] = useState(); + const [module, setModule] = useState | undefined>(); // Мы не хотим чтобы изменение этих параметров тригерило ререндер и перемонтирование модуля, // но не хотим ломать правила хуков const loaderParamsRef = useRef(loaderParams); diff --git a/packages/arui-scripts-modules/src/module-loader/hooks/use-module-mounter.ts b/packages/arui-scripts-modules/src/module-loader/hooks/use-module-mounter.ts index 2b43c6a8..aa76cbd9 100644 --- a/packages/arui-scripts-modules/src/module-loader/hooks/use-module-mounter.ts +++ b/packages/arui-scripts-modules/src/module-loader/hooks/use-module-mounter.ts @@ -1,5 +1,6 @@ import { useEffect, useRef, useState } from 'react'; +import { type ModuleExports } from '../module-contract'; import { createModuleSession } from '../module-session'; import { type ModuleMounterOptions, type MountableModule } from '../module-types'; import { type BaseModuleState, type Loader } from '../types'; @@ -15,7 +16,7 @@ export type UseModuleLoaderParams< /** * Загрузчик модуля */ - loader: Loader>; + loader: Loader>>; /** * Параметры, которые будут переданы в загрузчик (и будут переданы на сервер модуля) */ diff --git a/packages/arui-scripts-modules/src/module-loader/index.ts b/packages/arui-scripts-modules/src/module-loader/index.ts index cd3b2372..925ec94c 100644 --- a/packages/arui-scripts-modules/src/module-loader/index.ts +++ b/packages/arui-scripts-modules/src/module-loader/index.ts @@ -2,9 +2,11 @@ import 'abortcontroller-polyfill/dist/abortcontroller-polyfill-only'; export * from './types'; export * from './module-types'; +export * from './module-contract'; export * from './hooks/types'; export { createModuleLoader } from './create-module-loader'; +export { createTypedModuleLoader } from './create-typed-module-loader'; export { createModuleFetcher } from './create-module-fetcher'; export { createServerStateModuleFetcher } from './create-server-state-module-fetcher'; export { createEmbeddedModuleFetcher } from './create-embedded-module-fetcher'; diff --git a/packages/arui-scripts-modules/src/module-loader/module-contract.ts b/packages/arui-scripts-modules/src/module-loader/module-contract.ts new file mode 100644 index 00000000..d0d37698 --- /dev/null +++ b/packages/arui-scripts-modules/src/module-loader/module-contract.ts @@ -0,0 +1,39 @@ +// модуль может быть экспортирован напрямую или через default +export type ModuleExports = + | (Module & { default?: Module | null | undefined }) + | { default: Module }; + +type DefaultOrModule = Default extends null | undefined ? Module : Default; + +// берем default, а при null или undefined используем сам модуль +type UnwrapModule = Module extends { default?: unknown } + ? 'default' extends keyof Module + ? DefaultOrModule + : Module + : Module; + +// распознает функцию без ограничений на типы ее аргументов +type Callable = (...args: never[]) => unknown; + +// фабрика может быть самой функцией, полем factory или старым полем mount +type FactoryFunction = Module extends Callable + ? Module + : Module extends { factory: infer Factory extends Callable } + ? Factory + : Module extends { mount: infer Factory extends Callable } + ? Factory + : never; + +// у mount пропускаем первый аргумент (DOM-элемент), а у фабрики берем аргументы как есть +type ModuleArguments = Module extends { + mount: infer Mount extends Callable; + unmount: Callable; +} + ? [Parameters[1], Parameters[2]] + : Parameters>; + +// тип параметров запуска модуля или фабрики +export type ModuleRunParams = ModuleArguments>[0]; + +// тип серверного состояния, которое ожидает модуль или фабрика +export type ModuleServerState = ModuleArguments>[1]; diff --git a/packages/arui-scripts-modules/src/module-loader/module-session.ts b/packages/arui-scripts-modules/src/module-loader/module-session.ts index b864c704..50f9b2c3 100644 --- a/packages/arui-scripts-modules/src/module-loader/module-session.ts +++ b/packages/arui-scripts-modules/src/module-loader/module-session.ts @@ -1,5 +1,6 @@ import { MODULE_SSR_MODULE_ATTRIBUTE } from './utils/get-embedded-module-resources'; import { unwrapDefaultExport } from './utils/unwrap-default-export'; +import { type ModuleExports } from './module-contract'; import { createModuleLifecycle, reportModuleError } from './module-lifecycle'; import { type ModuleMounterErrorStage, @@ -12,7 +13,7 @@ type SessionParams = { load: ( signal: AbortSignal, onLoadError: (stage: ModuleMounterErrorStage) => void, - ) => Promise>>; + ) => Promise>>>; targetNode: HTMLElement; getRunParams: () => RunParams; getOptions: () => ModuleMounterOptions; @@ -20,7 +21,7 @@ type SessionParams = { }; export function resolveMountableModule( - exportedModule: MountableModule, + exportedModule: ModuleExports>, ) { const module = exportedModule && unwrapDefaultExport(exportedModule); @@ -52,7 +53,9 @@ export function createModuleSession> | undefined; + let result: + | LoaderResult>> + | undefined; try { result = await load(abortController.signal, (errorStage) => { diff --git a/packages/arui-scripts-modules/src/module-loader/module-types.ts b/packages/arui-scripts-modules/src/module-loader/module-types.ts index 80d8a3af..d5707034 100644 --- a/packages/arui-scripts-modules/src/module-loader/module-types.ts +++ b/packages/arui-scripts-modules/src/module-loader/module-types.ts @@ -135,7 +135,7 @@ export type FactoryModule< ServerState extends BaseModuleState = BaseModuleState, > = | FactoryModuleFunction - | { factory: FactoryModuleFunction; mount: never } - | { mount: FactoryModuleFunction; factory: never }; + | { factory: FactoryModuleFunction; mount?: never } + | { mount: FactoryModuleFunction; factory?: never }; export type WindowWithFactoryModule = WindowWithModule; diff --git a/packages/arui-scripts-modules/src/module-loader/utils/unwrap-default-export.ts b/packages/arui-scripts-modules/src/module-loader/utils/unwrap-default-export.ts index 062e8248..3f07fd04 100644 --- a/packages/arui-scripts-modules/src/module-loader/utils/unwrap-default-export.ts +++ b/packages/arui-scripts-modules/src/module-loader/utils/unwrap-default-export.ts @@ -1,7 +1,7 @@ -type ModuleWithDefaultField = { - default: T; -}; +import { type ModuleExports } from '../module-contract'; -export function unwrapDefaultExport(module: ModuleExportType): ModuleExportType { - return (module as ModuleWithDefaultField).default ?? module; +export function unwrapDefaultExport( + module: ModuleExports, +): ModuleExportType { + return module.default ?? (module as ModuleExportType); } diff --git a/packages/arui-scripts-modules/src/react/index.ts b/packages/arui-scripts-modules/src/react/index.ts index 7d1f51c4..87b0e28b 100644 --- a/packages/arui-scripts-modules/src/react/index.ts +++ b/packages/arui-scripts-modules/src/react/index.ts @@ -1,3 +1,7 @@ export { createReactModule } from './create-react-module'; export { useModuleReady } from './module-runtime'; export { type ReactModuleProps, type CreateReactModuleOptions } from './types'; +// типы из сигнатуры createReactModule: без них TypeScript не может назвать выведенный тип +// модуля через публичный подпуть, и генерация контрактов падает с TS2883 +export { type MountableModule } from '../module-loader/module-types'; +export { type BaseModuleState } from '../module-loader/types'; diff --git a/packages/arui-scripts/docs/commands.md b/packages/arui-scripts/docs/commands.md index f0b1d335..843d16cf 100644 --- a/packages/arui-scripts/docs/commands.md +++ b/packages/arui-scripts/docs/commands.md @@ -35,6 +35,9 @@ arui-scripts start:prod Если заданы [buildSizeBudgets](settings.md#buildsizebudgets), после клиентской сборки проверяются лимиты начального JS и CSS. Превышение останавливает сборку с ненулевым кодом. +Если задан `modules.types`, команда также готовит npm пакет с типами в `/module-contracts`. +Подробнее в разделе [генерация пакета контрактов](modules.md#генерация-пакета-контрактов). + **Как запустить?** ```bash diff --git a/packages/arui-scripts/docs/modules.md b/packages/arui-scripts/docs/modules.md index 1d6b179c..695b31b6 100644 --- a/packages/arui-scripts/docs/modules.md +++ b/packages/arui-scripts/docs/modules.md @@ -174,8 +174,8 @@ export const mount: ModuleMountFunction = (targetNode, runParam ```tsx import { createModuleLoader, MountableModule, useModuleMounter } from '@alfalab/scripts-modules'; -// У нас возможности передать типы из приложения-модуля в приложение-хост -// При желании вы можете вынести эти типы в общую библиотеку и использовать оттуда +// Без генерации контрактов типы нужно описать вручную +// или вынести в общую библиотеку. Автоматическая генерация описана ниже. type ModuleRunParams = { theme: string; width: number; @@ -200,6 +200,69 @@ export const MyAwesomeComponent = () => { } ``` +## Генерация пакета контрактов + +Пакет контрактов позволяет хосту использовать типы микрофронта без ручного копирования + +### В микрофронте + +Укажите в конфиге, какие модули экспортировать и задайте имя npm пакета с их типами + +```ts +export default { + modules: { + shared: {}, + exposes: { + SomeWidget: './src/modules/some-widget/index' + }, + types: { + packageName: '@namespace/some-widget-contracts' + }, + }, +}; +``` + +`arui-scripts build` создаст пакет в `/module-contracts`. +При стандартном `buildPath` опубликуйте его отдельной командой `npm publish ./.build/module-contracts`. + +По умолчанию версия берется из `package.json` микрофронта. +Переопределить ее можно через `modules.types.version`. Сборка проверяет формат semver. + +### В хосте + +Установите пакет как `devDependency` и добавьте недостающие зависимости из его `peerDependencies`. +Передайте `ModuleContracts` в `createTypedModuleLoader`. + +```tsx +import type { ModuleContracts } from '@namespace/some-widget-contracts'; +import { createModuleFetcher, createTypedModuleLoader, useModuleMounter } from '@alfalab/scripts-modules'; + +const createLoader = createTypedModuleLoader(); + +const loader = createLoader({ + moduleId: 'SomeWidget', + hostAppId: 'some-host', + getModuleResources: createModuleFetcher({ baseUrl: '/some-widget' }), +}); + +export const SomeWidget = () => { + const { targetElementRef } = useModuleMounter({ + loader, + runParams: { clientId: '123', width: 300 }, + }); + + return
; +}; +``` + +TypeScript проверит `moduleId` и переданные `runParams`. +Например, если `width` у микрофронта имеет тип `number`, строка `'300'` вызовет ошибку. +Весь объект `runParams` можно опустить. Используйте версию контракта, соответствующую развернутому микрофронту. + +Для генерации нужен TypeScript 5.x или 6.x. +Compat-модули и project references не поддерживаются. +Чтобы отключить генерацию, задайте `modules.types: false`. + :warning: **Внимание!** Модуль не будет обновляться при изменении runParams. Это осознанное решение, вы не должны относится к параметрам тут с той же легкостью, что и к prop-ам react-компонентов. Очень легко провести параллели между эти двумя концепциями, но использование runParams специально сделано менее удобным - чем меньше вы их используете, тем реже вы будете diff --git a/packages/arui-scripts/docs/settings.md b/packages/arui-scripts/docs/settings.md index f3e89f91..848ee192 100644 --- a/packages/arui-scripts/docs/settings.md +++ b/packages/arui-scripts/docs/settings.md @@ -385,6 +385,8 @@ export default settings; #### modules Позволяет настроить работу с модулями. По умолчанию `{}`. Подробнее в разделе [модули](modules.md). +`modules.types: { packageName: '@namespace/module-contracts', version?: string }` включает подготовку npm пакета деклараций из `modules.exposes` при production-сборке. `version` по умолчанию берется из `package.json` приложения. По умолчанию генерация выключена; `modules.types: false` явно отключает настройку из preset. Подробнее в разделе [генерация пакета контрактов](modules md#генерация-пакета-контрактов). + #### compatModules Позволяет настроить работу с `compat` модулями. По умолчанию `{}`. Подробнее в разделе [модули](modules.md). diff --git a/packages/arui-scripts/package.json b/packages/arui-scripts/package.json index 7416bbd0..aa0390c0 100644 --- a/packages/arui-scripts/package.json +++ b/packages/arui-scripts/package.json @@ -136,6 +136,7 @@ "webpack-node-externals": "3.0.0" }, "devDependencies": { + "@alfalab/scripts-modules": "workspace:*", "@rsdoctor/types": "1.6.4", "@types/assets-webpack-plugin": "6.1.2", "@types/case-sensitive-paths-webpack-plugin": "2.1.6", diff --git a/packages/arui-scripts/src/commands/build/client.ts b/packages/arui-scripts/src/commands/build/client.ts index 4a011923..a42b1d04 100644 --- a/packages/arui-scripts/src/commands/build/client.ts +++ b/packages/arui-scripts/src/commands/build/client.ts @@ -6,6 +6,7 @@ import { rspackClientConfig } from '../../configs/rspack.client.prod'; import { BuildSizeBudgetError, checkBuildSizeBudgets } from '../util/build-size-budgets'; import { printAssetsSizes } from '../util/client-assets-sizes'; import { loadBrowserslist } from '../util/load-browserslist'; +import { buildModuleContracts } from '../util/module-contracts/build-module-contracts'; import { printBuildError } from '../util/print-build-error'; import { enableRsdoctor, writeRsdoctorSnapshot } from '../util/rsdoctor-snapshot'; @@ -72,6 +73,8 @@ async function main() { if (snapshot) { await writeRsdoctorSnapshot(snapshot); } + + buildModuleContracts(configs); } catch (err) { if (err instanceof BuildSizeBudgetError) { process.exit(1); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__fixtures__/consumer.ts b/packages/arui-scripts/src/commands/util/module-contracts/__fixtures__/consumer.ts new file mode 100644 index 00000000..949518e2 --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__fixtures__/consumer.ts @@ -0,0 +1,40 @@ +export const consumerSource = ` + import type { ModuleContracts } from '@fixture/contracts'; + import { createTypedModuleLoader, useModuleMounter, useModuleFactory, createModuleFetcher, type ModuleRunParams, type ModuleServerState } from '@alfalab/scripts-modules'; + const createLoader = createTypedModuleLoader(); + const resources = createModuleFetcher({ baseUrl: '/provider' }); + const loader = createLoader({ moduleId: 'Credit', hostAppId: 'consumer', getModuleResources: resources }); + useModuleMounter({ loader, runParams: { clientId: '123', width: 300 } }); + useModuleMounter({ loader }); // Existing optionality is preserved. + // @ts-expect-error Wrong exposed module ID. + createLoader({ moduleId: 'Missing', hostAppId: 'consumer', getModuleResources: resources }); + // @ts-expect-error Wrong runParams value. + useModuleMounter({ loader, runParams: { clientId: '123', width: 'wide' } }); + // @ts-expect-error Missing required field in a provided object. + useModuleMounter({ loader, runParams: { width: 300 } }); + const defaultLoader = createLoader({ moduleId: 'ReactCredit', hostAppId: 'consumer', getModuleResources: resources }); + useModuleMounter({ loader: defaultLoader, runParams: { theme: 'dark' } }); + // @ts-expect-error Default exports preserve their parameters. + useModuleMounter({ loader: defaultLoader, runParams: { theme: 'blue' } }); + const factory = createLoader({ moduleId: 'Factory', hostAppId: 'consumer', getModuleResources: resources }); + const result = useModuleFactory({ loader: factory, runParams: { account: '123' }, getFactoryParams: state => ({ ...state, amount: state.amount + 1 }) }); + const balance: number | undefined = result.module?.balance; + // @ts-expect-error The factory result is not any. + const wrong: string | undefined = result.module?.balance; + // @ts-expect-error Factory parameters are checked. + useModuleFactory({ loader: factory, runParams: { account: 123 } }); + const params: ModuleRunParams = { clientId: '123', width: 300 }; + const state: ModuleServerState = { baseUrl: '', hostAppId: '', credit: { balance: 100 } }; + // @ts-expect-error Transitive external types survive publishing. + const invalid: ModuleServerState = { baseUrl: '', hostAppId: '', credit: { balance: '100' } }; + const factoryParams: ModuleRunParams = { account: '123' }; + `; + +const factoryBody = + '(params: { account: string }, state: { baseUrl: string; hostAppId: string; amount: number }) => ({ balance: state.amount });'; + +export const factorySources = { + default: `export default ${factoryBody}`, + named: `export const factory = ${factoryBody}`, + legacy: `export const mount = ${factoryBody}`, +}; diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__fixtures__/portable-contract.ts b/packages/arui-scripts/src/commands/util/module-contracts/__fixtures__/portable-contract.ts new file mode 100644 index 00000000..a370f188 --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__fixtures__/portable-contract.ts @@ -0,0 +1,158 @@ +import { execFileSync } from 'child_process'; +import fs from 'fs'; +import os from 'os'; +import path from 'path'; + +import { extract } from 'tar'; +import ts from 'typescript'; + +import { + getDefaultAppConfig, + getDefaultAppContext, +} from '../../../../configs/app-configs/get-defaults'; +import { buildModuleContracts } from '../build-module-contracts'; + +export function createPortableProject( + options: Record = {}, + exposes: Record = { Widget: './src/index' }, +) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'arui-portable-contract-')); + const cwd = path.join(root, 'provider'); + const write = (filename: string, text: string) => { + const target = path.join(cwd, filename); + + fs.mkdirSync(path.dirname(target), { recursive: true }); + fs.writeFileSync(target, text); + }; + + write('package.json', '{"name":"provider","version":"1.0.0"}'); + write( + 'tsconfig.json', + JSON.stringify({ + compilerOptions: { + strict: true, + target: 'es2022', + module: 'esnext', + moduleResolution: 'bundler', + types: [], + noEmit: true, + allowSyntheticDefaultImports: true, + ...options, + }, + include: ['src/**/*'], + }), + ); + fs.mkdirSync(path.join(cwd, 'node_modules'), { recursive: true }); + fs.symlinkSync( + path.dirname(require.resolve('typescript/package.json')), + path.join(cwd, 'node_modules/typescript'), + 'dir', + ); + const config = { + ...getDefaultAppConfig(), + ...getDefaultAppContext(), + cwd, + version: '1.0.0', + tsconfig: path.join(cwd, 'tsconfig.json'), + serverOutputPath: path.join(cwd, '.build'), + modules: { + shared: {}, + exposes, + types: { packageName: '@fixture/contracts' }, + }, + }; + + return { root, cwd, config, write }; +} + +export async function checkPackedConsumer( + project: ReturnType, + source: string, + dependencies: Record = {}, + consumerFormat: 'esm' | 'commonjs-node16' = 'esm', +) { + const { root, cwd, config } = project; + const parsed = ts.getParsedCommandLineOfConfigFile( + config.tsconfig, + {}, + { + ...ts.sys, + onUnRecoverableConfigFileDiagnostic: (diagnostic) => { + throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')); + }, + }, + ); + + if (!parsed) throw new Error('Expected producer configuration'); + const producer = ts.createProgram(parsed.fileNames, parsed.options); + + expect(ts.getPreEmitDiagnostics(producer)).toEqual([]); + const directory = buildModuleContracts(config); + + if (!directory) throw new Error('Expected contract package'); + const [packed] = JSON.parse( + execFileSync( + 'npm', + [ + 'pack', + directory, + '--json', + '--offline', + '--ignore-scripts', + '--pack-destination', + root, + '--cache', + path.join(root, 'npm-cache'), + ], + { encoding: 'utf8' }, + ), + ) as Array<{ filename: string; files: Array<{ path: string }> }>; + + expect( + packed.files.every( + (file) => file.path === 'package.json' || /\.d\.(ts|mts|cts)$/.test(file.path), + ), + ).toBe(true); + const consumer = path.join(root, 'consumer'); + const installed = path.join(consumer, 'node_modules/@fixture/contracts'); + + fs.mkdirSync(installed, { recursive: true }); + await extract({ file: path.join(root, packed.filename), cwd: installed, strip: 1 }); + const manifest = JSON.parse(fs.readFileSync(path.join(installed, 'package.json'), 'utf8')) as { + peerDependencies: Record; + }; + + Object.keys(manifest.peerDependencies).forEach((name) => { + const dependencyDirectory = dependencies[name]; + + if (!dependencyDirectory) return; + const target = path.join(consumer, 'node_modules', name); + + fs.mkdirSync(path.dirname(target), { recursive: true }); + fs.symlinkSync(dependencyDirectory, target, 'dir'); + }); + const commonjs = consumerFormat === 'commonjs-node16'; + const entrypoint = path.join(consumer, commonjs ? 'index.cts' : 'index.mts'); + + fs.writeFileSync(entrypoint, source); + fs.rmSync(cwd, { recursive: true, force: true }); + const program = ts.createProgram([entrypoint], { + noEmit: true, + strict: true, + skipLibCheck: false, + types: [], + module: commonjs ? ts.ModuleKind.Node16 : ts.ModuleKind.NodeNext, + moduleResolution: commonjs + ? ts.ModuleResolutionKind.Node16 + : ts.ModuleResolutionKind.NodeNext, + target: ts.ScriptTarget.ESNext, + }); + + expect( + ts + .getPreEmitDiagnostics(program) + .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')), + ).toEqual([]); + + return manifest; +} diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__tests__/ambient-contracts.tests.ts b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/ambient-contracts.tests.ts new file mode 100644 index 00000000..053f30d6 --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/ambient-contracts.tests.ts @@ -0,0 +1,116 @@ +import fs from 'fs'; +import path from 'path'; + +import { checkPackedConsumer, createPortableProject } from '../__fixtures__/portable-contract'; + +it('includes ambient types used by the contract without changing unrelated host globals', async () => { + const project = createPortableProject(); + const log = jest.spyOn(console, 'log').mockImplementation(() => undefined); + + try { + project.write('src/dto.d.ts', 'type ContractWidth = number;'); + project.write( + 'src/globals.d.ts', + 'export {}; declare global { interface ContractParams { width: ContractWidth } }', + ); + project.write('src/local.d.ts', 'interface Window { widgetLocalFlags: string }'); + project.write( + 'src/index.ts', + 'export const factory = (params: ContractParams) => params.width;', + ); + + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare global { interface Window { widgetLocalFlags: number } } + const local: number = window.widgetLocalFlags; + declare const widget: ModuleContracts['Widget']; + const width: number = widget.factory({ width: 123 }); + // @ts-expect-error The reachable ambient types retain their field types. + widget.factory({ width: '123' }); + `, + ); + } finally { + fs.rmSync(project.root, { recursive: true, force: true }); + log.mockRestore(); + } +}, 30000); + +it('references a package whose global augmentation is used by the contract', async () => { + const project = createPortableProject(); + const view = path.join(project.root, 'view'); + const log = jest.spyOn(console, 'log').mockImplementation(() => undefined); + + try { + project.write( + '../view/package.json', + '{"name":"@fixture/view","version":"3.1.4","types":"index.d.ts"}', + ); + // Как JSX в @types/react: глобальный тип приходит вместе с импортом модуля. + project.write( + '../view/index.d.ts', + 'export declare function render(): ViewNode.Element;\ndeclare global { namespace ViewNode { interface Element { tag: string } } }', + ); + fs.mkdirSync(path.join(project.cwd, 'node_modules/@fixture'), { recursive: true }); + fs.symlinkSync(view, path.join(project.cwd, 'node_modules/@fixture/view'), 'dir'); + // Импорт нужен только значению, поэтому из декларации он пропадает. + project.write( + 'src/index.ts', + "import { render } from '@fixture/view'; export const factory = (): ViewNode.Element => render();", + ); + + const manifest = await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const tag: string = widget.factory().tag; + // @ts-expect-error The global type retains its fields. + const wrong: number = widget.factory().tag; + `, + { '@fixture/view': view }, + ); + + expect(manifest.peerDependencies).toEqual({ '@fixture/view': '^3.1.0' }); + } finally { + fs.rmSync(project.root, { recursive: true, force: true }); + log.mockRestore(); + } +}, 30000); + +it('keeps reference paths when one of them is a substring of another', async () => { + const project = createPortableProject(); + const log = jest.spyOn(console, 'log').mockImplementation(() => undefined); + + try { + project.write('src/a.d.ts', 'type ContractWidth = number;'); + project.write('src/dto/a.d.ts', 'type ContractHeight = string;'); + project.write( + 'src/dto/index.d.ts', + [ + '/// ', + '/// ', + 'export type Size = { width: ContractWidth; height: ContractHeight };', + ].join('\n'), + ); + project.write( + 'src/index.ts', + "import type { Size } from './dto'; export const factory = (size: Size) => size;", + ); + + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + widget.factory({ width: 1, height: '1' }); + // @ts-expect-error Both referenced declarations retain their types. + widget.factory({ width: '1', height: 1 }); + `, + ); + } finally { + fs.rmSync(project.root, { recursive: true, force: true }); + log.mockRestore(); + } +}, 30000); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__tests__/build-module-contracts.tests.ts b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/build-module-contracts.tests.ts new file mode 100644 index 00000000..7f8aa2b7 --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/build-module-contracts.tests.ts @@ -0,0 +1,282 @@ +import fs from 'fs'; +import os from 'os'; +import path from 'path'; + +import ts from 'typescript'; + +import { + getDefaultAppConfig, + getDefaultAppContext, +} from '../../../../configs/app-configs/get-defaults'; +import { type AppContextWithConfigs } from '../../../../configs/app-configs/types'; +import { consumerSource, factorySources } from '../__fixtures__/consumer'; +import { buildModuleContracts } from '../build-module-contracts'; + +describe('module contracts', () => { + let root: string; + let cwd: string; + let config: AppContextWithConfigs; + + const write = (filename: string, content: string) => { + fs.mkdirSync(path.dirname(filename), { recursive: true }); + fs.writeFileSync(filename, content); + }; + const link = (source: string, target: string) => { + fs.mkdirSync(path.dirname(target), { recursive: true }); + fs.symlinkSync(source, target, 'dir'); + }; + const output = () => path.join(cwd, '.build/module-contracts'); + const readPackage = () => + JSON.parse(fs.readFileSync(path.join(output(), 'package.json'), 'utf8')); + + beforeEach(() => { + root = fs.mkdtempSync(path.join(os.tmpdir(), 'arui-contract-test-')); + cwd = path.join(root, 'provider'); + write( + path.join(cwd, 'package.json'), + JSON.stringify({ + name: 'provider', + version: '1.2.3', + dependencies: { + '@fixture/dto': '^2.0.0', + '@alfalab/scripts-modules': 'workspace:*', + }, + }), + ); + write( + path.join(cwd, 'tsconfig.json'), + JSON.stringify({ + compilerOptions: { + strict: true, + target: 'es2022', + module: 'esnext', + moduleResolution: 'bundler', + noEmit: true, + types: [], + paths: { '#/*': ['./src/*'] }, + }, + include: ['src/**/*.ts', 'global.d.ts'], + }), + ); + write(path.join(cwd, 'global.d.ts'), 'declare module "*.css";'); + write( + path.join(cwd, 'src/params.ts'), + 'export type Params = { clientId: string; width: number };', + ); + write( + path.join(root, 'dto/package.json'), + JSON.stringify({ name: '@fixture/dto', version: '2.0.1', types: './index.d.ts' }), + ); + write(path.join(root, 'dto/index.d.ts'), 'export type Credit = { balance: number };'); + link( + path.dirname(require.resolve('typescript/package.json')), + path.join(cwd, 'node_modules/typescript'), + ); + link(path.join(root, 'dto'), path.join(cwd, 'node_modules/@fixture/dto')); + link( + path.dirname(require.resolve('@alfalab/scripts-modules/package.json')), + path.join(cwd, 'node_modules/@alfalab/scripts-modules'), + ); + write( + path.join(cwd, 'src/credit.ts'), + ` + import type { Params } from '#/params'; + import type { Credit } from '@fixture/dto'; + import './styles.css'; + export function mount(target: HTMLElement, params: Params, state: { baseUrl: string; hostAppId: string; credit: Credit }): void {} + export function unmount(): void {} + `, + ); + write( + path.join(cwd, 'src/default.ts'), + ` + import { createReactModule, type ReactModuleProps } from '@alfalab/scripts-modules/react'; + export default createReactModule({ Component: (props: ReactModuleProps<{ theme: 'light' | 'dark' }>) => null }); + `, + ); + write( + path.join(cwd, 'src/factory.ts'), + ` + export default (params: { account: string }, state: { baseUrl: string; hostAppId: string; amount: number }) => ({ balance: state.amount }); + `, + ); + config = { + ...getDefaultAppConfig(), + ...getDefaultAppContext(), + cwd, + version: '1.2.3', + tsconfig: path.join(cwd, 'tsconfig.json'), + serverOutputPath: path.join(cwd, '.build'), + modules: { + shared: {}, + exposes: { + Credit: './src/credit', + ReactCredit: './src/default', + Factory: './src/factory', + }, + types: { packageName: '@fixture/contracts' }, + }, + }; + jest.spyOn(console, 'log').mockImplementation(() => undefined); + }); + + afterEach(() => { + fs.rmSync(root, { recursive: true, force: true }); + jest.restoreAllMocks(); + }); + + it.each(Object.entries(factorySources))( + 'checks a portable %s factory without producer sources', + (_kind, source) => { + write(path.join(cwd, 'src/factory.ts'), source); + const directory = buildModuleContracts(config); + + expect(directory).toBe(output()); + if (!directory) throw new Error('Expected contracts'); + const metadata = readPackage(); + + expect(metadata).toMatchObject({ + name: '@fixture/contracts', + version: '1.2.3', + peerDependencies: { '@fixture/dto': '^2.0.0' }, + }); + expect(metadata).not.toHaveProperty('dependencies'); + expect(metadata.peerDependencies['@alfalab/scripts-modules']).toMatch( + /^\^\d+\.\d+\.0$/, + ); + expect(buildModuleContracts(config)).toBe(directory); + expect( + fs.readFileSync(path.join(directory, 'declarations/src/credit.d.ts'), 'utf8'), + ).not.toContain('#/'); + const consumer = path.join(root, 'consumer'); + + fs.cpSync(directory, path.join(consumer, 'node_modules/@fixture/contracts'), { + recursive: true, + }); + link(path.join(root, 'dto'), path.join(consumer, 'node_modules/@fixture/dto')); + link( + path.dirname(require.resolve('@alfalab/scripts-modules/package.json')), + path.join(consumer, 'node_modules/@alfalab/scripts-modules'), + ); + write(path.join(consumer, 'package.json'), '{"type":"module"}'); + write(path.join(consumer, 'index.ts'), consumerSource); + fs.rmSync(cwd, { recursive: true, force: true }); + const program = ts.createProgram([path.join(consumer, 'index.ts')], { + noEmit: true, + strict: true, + skipLibCheck: false, + types: [], + target: ts.ScriptTarget.ESNext, + module: ts.ModuleKind.NodeNext, + moduleResolution: ts.ModuleResolutionKind.NodeNext, + }); + const diagnostics = ts.getPreEmitDiagnostics(program); + + expect( + diagnostics.map((diagnostic) => + ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'), + ), + ).toEqual([]); + }, + 60000, + ); + + it('names createReactModule types without the main package entry in the program', () => { + if (!config.modules) throw new Error('Expected modules'); + config.modules.exposes = { ReactCredit: './src/default' }; + + expect(buildModuleContracts(config)).toBe(output()); + }, 30000); + + it('removes a previous package when generation fails', () => { + buildModuleContracts(config); + write(path.join(cwd, 'src/credit.ts'), 'export const broken: number = "text";'); + + expect(() => buildModuleContracts(config)).toThrow('not assignable'); + expect(fs.existsSync(output())).toBe(false); + }, 30000); + + it('uses modules.types.version instead of the application version', () => { + if (!config.modules?.types) throw new Error('Expected modules.types'); + config.modules.types.version = '2.0.0-rc.1'; + config.version = 'next'; + buildModuleContracts(config); + + expect(readPackage().version).toBe('2.0.0-rc.1'); + }, 30000); + + it('requires a SemVer package version', () => { + config.version = 'next'; + + expect(() => buildModuleContracts(config)).toThrow('SemVer'); + }); + + it('rejects a non-SemVer override even if the application version is valid', () => { + if (!config.modules?.types) throw new Error('Expected modules.types'); + config.modules.types.version = 'next'; + + expect(() => buildModuleContracts(config)).toThrow('SemVer'); + }); + + it('ignores unrelated declaration conflicts in provider environment types', () => { + const tsconfig = JSON.parse(fs.readFileSync(config.tsconfig as string, 'utf8')); + const environment = path.join(cwd, 'node_modules/@fixture/environment'); + + tsconfig.compilerOptions.types = ['@fixture/environment']; + write(config.tsconfig as string, JSON.stringify(tsconfig)); + write( + path.join(environment, 'package.json'), + JSON.stringify({ + name: '@fixture/environment', + version: '1.0.0', + types: './index.d.ts', + }), + ); + write( + path.join(environment, 'index.d.ts'), + ` + interface EnvironmentBase { version: string } + interface LegacyEnvironment extends EnvironmentBase { version: number } + `, + ); + + expect(() => buildModuleContracts(config)).not.toThrow(); + }, 30000); + + it('does not read or generate anything when disabled', () => { + if (!config.modules) throw new Error('Expected modules'); + config.modules.types = false; + fs.rmSync(cwd, { recursive: true, force: true }); + + expect(buildModuleContracts(config)).toBeUndefined(); + }); + + it('still rejects invalid declarations included in the public contract', () => { + write( + path.join(cwd, 'src/params.d.ts'), + ` + interface BaseParams { clientId: string } + export interface Params extends BaseParams { clientId: number; width: number } + `, + ); + fs.rmSync(path.join(cwd, 'src/params.ts')); + + expect(() => buildModuleContracts(config)).toThrow('incorrectly extends'); + expect(fs.existsSync(output())).toBe(false); + }, 30000); + + it('rejects declarations relying on unexported provider globals and removes them', () => { + const tsconfig = JSON.parse(fs.readFileSync(config.tsconfig as string, 'utf8')); + + tsconfig.compilerOptions.types = ['node']; + write(config.tsconfig as string, JSON.stringify(tsconfig)); + link( + path.dirname(require.resolve('@types/node/package.json')), + path.join(cwd, 'node_modules/@types/node'), + ); + write(path.join(cwd, 'src/credit.ts'), 'export type State = NodeJS.Process;'); + + expect(() => buildModuleContracts(config)).toThrow('без настроек проекта микрофронта'); + expect(fs.existsSync(output())).toBe(false); + }, 30000); +}); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__tests__/consumer-contracts.tests.ts b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/consumer-contracts.tests.ts new file mode 100644 index 00000000..c890009d --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/consumer-contracts.tests.ts @@ -0,0 +1,95 @@ +import fs from 'fs'; +import path from 'path'; + +import { checkPackedConsumer, createPortableProject } from '../__fixtures__/portable-contract'; + +it('types typed mounters and factories according to the exports they execute', async () => { + const project = createPortableProject( + {}, + { + Widget: './src/index', + BadMounter: './src/bad-mounter', + BadFactory: './src/bad-factory', + Named: './src/named', + NullDefault: './src/null-default', + }, + ); + const log = jest.spyOn(console, 'log').mockImplementation(() => undefined); + const scriptsModules = path.dirname(require.resolve('@alfalab/scripts-modules/package.json')); + + try { + project.write( + 'package.json', + JSON.stringify({ + name: 'provider', + version: '1.0.0', + dependencies: { '@alfalab/scripts-modules': 'workspace:*' }, + }), + ); + fs.mkdirSync(path.join(project.cwd, 'node_modules/@alfalab'), { recursive: true }); + fs.symlinkSync( + scriptsModules, + path.join(project.cwd, 'node_modules/@alfalab/scripts-modules'), + 'dir', + ); + project.write( + 'src/index.ts', + ` + import type { BaseModuleState } from '@alfalab/scripts-modules'; + export default async (params: { width: number }, state: BaseModuleState) => ({ + width: params.width, baseUrl: state.baseUrl + }); + `, + ); + project.write( + 'src/bad-mounter.ts', + "export default '1.0'; export function mount() {} export function unmount() {}", + ); + project.write( + 'src/bad-factory.ts', + "export default '1.0'; export const factory = () => 1;", + ); + const namedFactory = ` + export function factory(params: { width: number }, state: { baseUrl: string; hostAppId: string }) { + return params.width; + } + export function unmount() {} + `; + + project.write('src/named.ts', namedFactory); + project.write('src/null-default.ts', `${namedFactory}\nexport default null;`); + + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + import { + createTypedModuleLoader, createModuleFetcher, useModuleFactory, useModuleMounter, + type ModuleRunParams, type ModuleServerState, + } from '@alfalab/scripts-modules'; + const load = createTypedModuleLoader(); + const options = { + hostAppId: 'host', getModuleResources: createModuleFetcher({ baseUrl: '/provider' }), + }; + const asyncLoader = load({ ...options, moduleId: 'Widget' }); + const result = useModuleFactory({ loader: asyncLoader, runParams: { width: 100 } }); + const width: number | undefined = result.module?.width; + // @ts-expect-error The hook exposes the awaited result. + result.module?.then(() => undefined); + // @ts-expect-error A string default takes precedence over named mount and unmount. + useModuleMounter({ loader: load({ ...options, moduleId: 'BadMounter' }) }); + // @ts-expect-error A string default takes precedence over the named factory. + useModuleFactory({ loader: load({ ...options, moduleId: 'BadFactory' }) }); + const params: ModuleRunParams = { width: 100 }; + const state: ModuleServerState = { baseUrl: '', hostAppId: '' }; + const fallback: ModuleRunParams = params; + const namedLoader = load({ ...options, moduleId: 'NullDefault' }); + const fallbackResult: number | undefined = useModuleFactory({ loader: namedLoader, runParams: fallback }).module; + `, + { '@alfalab/scripts-modules': scriptsModules }, + ); + } finally { + fs.rmSync(project.root, { recursive: true, force: true }); + log.mockRestore(); + } +}, 30000); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__tests__/js-contracts.tests.ts b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/js-contracts.tests.ts new file mode 100644 index 00000000..0df4c54d --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/js-contracts.tests.ts @@ -0,0 +1,41 @@ +import fs from 'fs'; + +import { checkPackedConsumer, createPortableProject } from '../__fixtures__/portable-contract'; + +describe('JS dependencies of TypeScript module contracts', () => { + let project: ReturnType; + + beforeEach(() => { + project = createPortableProject({ allowJs: true, checkJs: true }); + project.write( + 'src/helper.js', + '/** @param {number} delta */ export const makeResult = (delta) => ({ balance: 42 + delta });', + ); + project.write( + 'src/index.ts', + "import { makeResult } from './helper.js'; export { makeResult } from './helper.js'; export const factory = (params: { account: string }) => makeResult(params.account.length);", + ); + jest.spyOn(console, 'log').mockImplementation(() => undefined); + }); + + afterEach(() => { + fs.rmSync(project.root, { recursive: true, force: true }); + jest.restoreAllMocks(); + }); + + it('packs declarations for JS helpers and preserves their public types in an isolated consumer', async () => { + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const balance: number = widget.factory({ account: '123' }).balance; + const helperBalance: number = widget.makeResult(1).balance; + // @ts-expect-error The JS helper must not lose its inferred result. + const invalid: string = widget.makeResult(1).balance; + // @ts-expect-error JSDoc parameter types must survive publishing. + widget.makeResult('1'); + `, + ); + }, 30000); +}); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__tests__/json-contracts.tests.ts b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/json-contracts.tests.ts new file mode 100644 index 00000000..60cf4b66 --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/json-contracts.tests.ts @@ -0,0 +1,101 @@ +import fs from 'fs'; + +import { checkPackedConsumer, createPortableProject } from '../__fixtures__/portable-contract'; + +describe('JSON dependencies in module contracts', () => { + let project: ReturnType; + + beforeEach(() => { + project = createPortableProject({ resolveJsonModule: true }); + project.write( + 'src/config.json', + JSON.stringify({ + width: 300, + options: { enabled: true }, + tags: ['some'], + empty: null, + }), + ); + jest.spyOn(console, 'log').mockImplementation(() => undefined); + }); + + afterEach(() => { + fs.rmSync(project.root, { recursive: true, force: true }); + jest.restoreAllMocks(); + }); + + it('allows a JSON import used only by the implementation', async () => { + project.write( + 'src/index.ts', + "import config from './config.json'; export const width = () => config.width;", + ); + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const width: number = widget.width(); + // @ts-expect-error The implementation's JSON still gives a precise return type. + const invalid: string = widget.width(); + `, + ); + }, 30000); + + it('publishes JSON types without requiring JSON files or compiler options in the consumer', async () => { + project.write('src/index.ts', "export { default as settings } from './config.json';"); + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const width: number = widget.settings.width; + const enabled: boolean = widget.settings.options.enabled; + const tag: string = widget.settings.tags[0]; + const empty: null = widget.settings.empty; + // @ts-expect-error JSON types must not degrade to any. + const invalid: string = widget.settings.width; + `, + ); + }, 30000); + + it('preserves the JSON object imported with require in a CommonJS entrypoint', async () => { + const config = JSON.parse(fs.readFileSync(project.config.tsconfig, 'utf8')); + + config.compilerOptions.module = 'nodenext'; + config.compilerOptions.moduleResolution = 'nodenext'; + project.write('tsconfig.json', JSON.stringify(config)); + project.config.modules.exposes.Widget = './src/index.cts'; + project.write( + 'src/index.cts', + "import config = require('./config.json'); const width: number = config.width; export { config };", + ); + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const width: number = widget.config.width; + const enabled: boolean = widget.config.options.enabled; + // @ts-expect-error The object from require must retain its property types. + const invalid: string = widget.config.width; + `, + ); + }, 30000); + + it('preserves a namespace JSON import', async () => { + project.write( + 'src/index.ts', + "import * as config from './config.json'; const width: number = config.width; export { config };", + ); + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const width: number = widget.config.width; + // @ts-expect-error Namespace imports must not introduce a default-only wrapper. + const invalid: string = widget.config.width; + `, + ); + }, 30000); +}); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__tests__/local-dependencies.tests.ts b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/local-dependencies.tests.ts new file mode 100644 index 00000000..a1b92b9f --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/local-dependencies.tests.ts @@ -0,0 +1,65 @@ +import fs from 'fs'; +import path from 'path'; + +import { checkPackedConsumer, createPortableProject } from '../__fixtures__/portable-contract'; + +describe('local dependencies with separate declarations', () => { + let project: ReturnType; + + beforeEach(() => { + project = createPortableProject(); + project.write('../foo/package.json', '{"name":"foo","version":"1.2.3","main":"index.js"}'); + project.write('../foo/index.js', 'module.exports = {};'); + project.write( + '../foo-types/package.json', + '{"name":"@types/foo","version":"1.2.4","types":"index.d.ts"}', + ); + project.write('../foo-types/index.d.ts', 'export type DTO = { account: string };'); + fs.mkdirSync(path.join(project.cwd, 'node_modules/@types'), { recursive: true }); + fs.symlinkSync( + path.join(project.root, 'foo'), + path.join(project.cwd, 'node_modules/foo'), + 'dir', + ); + fs.symlinkSync( + path.join(project.root, 'foo-types'), + path.join(project.cwd, 'node_modules/@types/foo'), + 'dir', + ); + project.write( + 'src/index.ts', + "import type { DTO } from 'foo'; export function factory(params: DTO) { return params.account; }", + ); + jest.spyOn(console, 'log').mockImplementation(() => undefined); + }); + + afterEach(() => { + fs.rmSync(project.root, { recursive: true, force: true }); + jest.restoreAllMocks(); + }); + + it('requires only the installed package that provides the declarations', async () => { + project.write( + 'package.json', + JSON.stringify({ + name: 'provider', + version: '1.0.0', + dependencies: { foo: 'workspace:*' }, + devDependencies: { '@types/foo': '1.2.4' }, + }), + ); + const metadata = await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const account: string = widget.factory({ account: '123' }); + // @ts-expect-error The separately published DTO must retain its fields. + widget.factory({ account: 123 }); + `, + { '@types/foo': path.join(project.root, 'foo-types') }, + ); + + expect(metadata.peerDependencies).toEqual({ '@types/foo': '^1.2.0' }); + }, 30000); +}); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/__tests__/module-formats.tests.ts b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/module-formats.tests.ts new file mode 100644 index 00000000..8d41a00f --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/__tests__/module-formats.tests.ts @@ -0,0 +1,197 @@ +import fs from 'fs'; +import path from 'path'; + +import { checkPackedConsumer, createPortableProject } from '../__fixtures__/portable-contract'; + +describe('module format of published contracts', () => { + let project: ReturnType; + + beforeEach(() => { + project = createPortableProject({ module: 'nodenext', moduleResolution: 'nodenext' }); + jest.spyOn(console, 'log').mockImplementation(() => undefined); + }); + + afterEach(() => { + fs.rmSync(project.root, { recursive: true, force: true }); + jest.restoreAllMocks(); + }); + + it('supports the documented import type in a CommonJS Node16 host', async () => { + project.write('package.json', '{"name":"provider","version":"1.0.0","type":"module"}'); + project.write('src/index.ts', 'export const factory = (width: number) => width;'); + + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const width: number = widget.factory(123); + // @ts-expect-error The ESM entrypoint retains its types in a CommonJS host. + widget.factory('123'); + `, + {}, + 'commonjs-node16', + ); + }, 30000); + + it('declares dependencies available only through exports.import', async () => { + project.write( + 'package.json', + JSON.stringify({ + name: 'provider', + version: '1.0.0', + type: 'module', + dependencies: { 'import-only': '1.0.0' }, + }), + ); + project.write( + '../import-only/package.json', + JSON.stringify({ + name: 'import-only', + version: '1.0.0', + exports: { import: './index.d.mts' }, + }), + ); + project.write('../import-only/index.d.mts', "export type Mode = 'import';"); + const dependency = path.join(project.root, 'import-only'); + + fs.symlinkSync(dependency, path.join(project.cwd, 'node_modules/import-only'), 'dir'); + project.write( + 'src/index.ts', + "import type { Mode } from 'import-only'; export const factory = (mode: Mode) => mode;", + ); + const manifest = await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const mode: 'import' = widget.factory('import'); + // @ts-expect-error The installed dependency defines a literal type. + widget.factory('require'); + `, + { 'import-only': dependency }, + ); + + expect(manifest.peerDependencies).toEqual({ 'import-only': '^1.0.0' }); + }, 30000); + + it('rewrites a conditional package import using the ESM provider branch', async () => { + project.write( + 'package.json', + JSON.stringify({ + name: 'provider', + version: '1.0.0', + type: 'module', + imports: { '#mode': { import: './src/esm.ts', require: './src/cjs.cts' } }, + }), + ); + project.write('src/esm.ts', "export type Mode = 'import';"); + project.write('src/cjs.cts', "export type Mode = 'require';"); + project.write( + 'src/index.ts', + "import type { Mode } from '#mode'; export const factory = (mode: Mode) => mode;", + ); + + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const mode: 'import' = widget.factory('import'); + // @ts-expect-error The local import must keep its ESM branch. + widget.factory('require'); + `, + ); + }, 30000); + + it.each([ + ['nodenext', 'commonjs', 'require', 'import'], + ['nodenext', 'module', 'import', 'require'], + ['node18', 'commonjs', 'require', 'import'], + ['node20', 'commonjs', 'require', 'import'], + ])( + 'preserves external types for module=%s and package type=%s', + async (module, type, expected, rejected) => { + const config = JSON.parse(fs.readFileSync(project.config.tsconfig, 'utf8')); + + config.compilerOptions.module = module; + delete config.compilerOptions.moduleResolution; + project.write('tsconfig.json', JSON.stringify(config)); + project.write( + 'package.json', + JSON.stringify({ + name: 'provider', + version: '1.0.0', + type, + dependencies: { dual: '1.0.0' }, + }), + ); + project.write( + '../dual/package.json', + JSON.stringify({ + name: 'dual', + version: '1.0.0', + exports: { '.': { import: './esm.d.mts', require: './cjs.d.cts' } }, + }), + ); + project.write('../dual/esm.d.mts', "export type Mode = 'import';"); + project.write('../dual/cjs.d.cts', "export type Mode = 'require';"); + const dual = path.join(project.root, 'dual'); + + fs.symlinkSync(dual, path.join(project.cwd, 'node_modules/dual'), 'dir'); + project.write( + 'src/index.ts', + ` + import type { Mode } from 'dual'; + const valid: Mode = '${expected}'; + export function factory(params: { mode: Mode }) { return params.mode; } + `, + ); + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const widget: ModuleContracts['Widget']; + const mode: '${expected}' = widget.factory({ mode: '${expected}' }); + // @ts-expect-error Publishing must not switch the import/require condition. + widget.factory({ mode: '${rejected}' }); + `, + { dual }, + ); + }, + 30000, + ); + + it.each([ + ['nodenext', 'nodenext'], + ['commonjs', 'node10'], + ])( + 'preserves export assignment with module=%s', + async (module, moduleResolution) => { + const config = JSON.parse(fs.readFileSync(project.config.tsconfig, 'utf8')); + + config.compilerOptions = { + ...config.compilerOptions, + module, + moduleResolution, + ignoreDeprecations: '6.0', + }; + project.write('tsconfig.json', JSON.stringify(config)); + project.write( + 'src/index.ts', + 'function factory(params: { width: number }) { return params.width; } export = factory;', + ); + await checkPackedConsumer( + project, + ` + import type { ModuleContracts } from '@fixture/contracts'; + declare const factory: ModuleContracts['Widget']; + const width: number = factory({ width: 300 }); + // @ts-expect-error The CommonJS function must retain its parameter type. + factory({ width: '300' }); + `, + ); + }, + 30000, + ); +}); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/build-module-contracts.ts b/packages/arui-scripts/src/commands/util/module-contracts/build-module-contracts.ts new file mode 100644 index 00000000..4edf38bf --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/build-module-contracts.ts @@ -0,0 +1,110 @@ +import fs from 'fs'; +import path from 'path'; + +import { gte, valid } from 'semver'; +import type * as TypeScript from 'typescript'; + +import { type AppContextWithConfigs } from '../../../configs/app-configs/types'; + +import { generateModuleDeclarations } from './generate-declarations'; +import { formatDiagnostics, requireProjectTypeScript } from './project-typescript'; + +/** Каталог пакета контрактов внутри buildPath: вне публичной статики, очищается каждой сборкой. */ +export const MODULE_CONTRACTS_DIRECTORY = 'module-contracts'; + +/** Готовит npm-пакет контрактов; при ошибке генерации или проверки не оставляет файлов. */ +export function buildModuleContracts(config: AppContextWithConfigs) { + if (!config.modules?.types) return undefined; + const { types: settings, exposes } = config.modules; + const version = valid(settings.version ?? config.version); + + if (!version) { + throw new Error( + 'modules.types: укажите SemVer-версию в modules.types.version или в package.json приложения.', + ); + } + const directory = path.join(config.serverOutputPath, MODULE_CONTRACTS_DIRECTORY); + + // Пакет прошлого запуска не должен пережить неудачную генерацию. + fs.rmSync(directory, { recursive: true, force: true }); + const ts = requireProjectTypeScript(config.cwd); + const { files, peerDependencies } = generateModuleDeclarations({ + ts, + cwd: config.cwd, + tsconfig: config.tsconfig as string, + exposes: exposes as Record, + }); + + files.set( + 'package.json', + `${JSON.stringify( + { + name: settings.packageName, + version, + type: 'module', + types: './index.d.ts', + exports: { + '.': { + import: { types: './index.d.ts' }, + require: { types: './index.d.cts' }, + }, + }, + files: ['**/*.d.ts', '**/*.d.mts', '**/*.d.cts'], + peerDependencies: Object.fromEntries( + Object.entries(peerDependencies).sort(([a], [b]) => a.localeCompare(b)), + ), + }, + null, + 2, + )}\n`, + ); + + try { + files.forEach((text, filename) => { + const target = path.join(directory, filename); + + fs.mkdirSync(path.dirname(target), { recursive: true }); + fs.writeFileSync(target, text); + }); + validateDeclarations(ts, config.cwd, directory); + } catch (error) { + fs.rmSync(directory, { recursive: true, force: true }); + throw error; + } + + console.log(`Module contracts: ${settings.packageName}@${version} → ${directory}`); + + return directory; +} + +/** Проверяет декларации без настроек TypeScript из проекта микрофронта. */ +function validateDeclarations(ts: typeof TypeScript, cwd: string, directory: string) { + const entrypoints = ['index.d.ts']; + + // `resolution-mode` в `export type ... with` из index.d.cts поддерживается с TypeScript 5.3. + if (gte(ts.version, '5.3.0')) entrypoints.push('index.d.cts'); + const program = ts.createProgram( + entrypoints.map((file) => path.join(directory, file)), + { + noEmit: true, + strict: true, + skipLibCheck: false, + target: ts.ScriptTarget.ESNext, + module: ts.ModuleKind.NodeNext, + moduleResolution: ts.ModuleResolutionKind.NodeNext, + types: [], + lib: ['lib.esnext.d.ts', 'lib.dom.d.ts'], + }, + ); + const diagnostics = ts.getPreEmitDiagnostics(program); + + if (diagnostics.length) { + throw new Error( + `modules.types: декларации не проходят проверку без настроек проекта микрофронта.\n${formatDiagnostics( + ts, + cwd, + diagnostics, + )}`, + ); + } +} diff --git a/packages/arui-scripts/src/commands/util/module-contracts/contract-dependencies.ts b/packages/arui-scripts/src/commands/util/module-contracts/contract-dependencies.ts new file mode 100644 index 00000000..9ed078e0 --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/contract-dependencies.ts @@ -0,0 +1,74 @@ +import fs from 'fs'; +import path from 'path'; + +import { parse } from 'semver'; + +type PackageMetadata = { + name: string; + version: string +}; + +export function packageForFile(filename: string): PackageMetadata | undefined { + let directory = path.dirname(filename); + + while (directory !== path.dirname(directory)) { + const metadata = path.join(directory, 'package.json'); + + if (fs.existsSync(metadata)) { + const { name, version } = JSON.parse( + fs.readFileSync(metadata, 'utf8'), + ) as Partial; + + if (name && version) { + return { + name, + version + }; + } + } + + directory = path.dirname(directory); + } + + return undefined; +} + +// cтроит диапазон совместимости по версии пакета в проекте микрофронта +function compatibleRange({ name, version }: PackageMetadata) { + const parsed = parse(version); + + if (!parsed) { + throw new Error(`modules.types: некорректная версия ${name}@${version}.`); + } + + const { major, minor, prerelease } = parsed; + + return prerelease.length || (!major && !minor) ? `^${parsed.version}` : `^${major}.${minor}.0`; +} + +// Собирает peerDependencies пакета контрактов: npm пакеты, которые отдают декларации, +// используемые публичными типами. Хост устанавливает их сам, поэтому копии типов не дублируются. + +export function createContractDependencies() { + const peerDependencies: Record = {}; + const addDependency = (specifier: string, resolvedFile: string | undefined) => { + const owner = resolvedFile ? packageForFile(resolvedFile) : undefined; + + if (!owner) { + throw new Error( + `modules.types: не удалось определить npm-пакет с типами ${specifier}.`, + ); + } + peerDependencies[owner.name] = compatibleRange(owner); + + return owner.name; + }; + + return { + peerDependencies, + addDependency + }; +} + +// имя для `/// `: пакет `@types/foo` подключается как `foo` +export const typeReferenceName = (packageName: string) => packageName.replace(/^@types\//, ''); diff --git a/packages/arui-scripts/src/commands/util/module-contracts/declaration-paths.ts b/packages/arui-scripts/src/commands/util/module-contracts/declaration-paths.ts new file mode 100644 index 00000000..76860d09 --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/declaration-paths.ts @@ -0,0 +1,76 @@ +import path from 'path'; + +import type * as TypeScript from 'typescript'; + +export const slash = (value: string) => value.split(path.sep).join('/'); + +function declarationPath(source: string, cwd: string, suffix: string) { + const relative = path.relative(cwd, source); + + if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) { + throw new Error(`Контракт ссылается на файл за пределами проекта: ${source}`); + } + + if (relative.endsWith('.json')) { + return `declarations/${slash(relative)}.d.cts`; + } + + if (relative.endsWith('.d.ts')) { + return `declarations/${slash(relative.slice(0, -5))}${suffix}`; + } + + return `declarations/${slash(relative).replace( + /(? { + if (ext === 'mts' || ext === 'mjs') return '.d.mts'; + if (ext === 'cts' || ext === 'cjs') return '.d.cts'; + + return suffix; + }, + )}`; +} + +export function createDeclarationPath( + ts: typeof TypeScript, + program: TypeScript.Program, + cwd: string, +) { + const { module } = program.getCompilerOptions(); + const nodeFormat = + module !== undefined && + [ + ts.ModuleKind.Node16, + ts.ModuleKind.Node18, + ts.ModuleKind.Node20, + ts.ModuleKind.NodeNext, + ].includes(module); + + return (filename: string) => { + let format = nodeFormat ? program.getSourceFile(filename)?.impliedNodeFormat : undefined; + + if (module === ts.ModuleKind.CommonJS) { + format = module; + } + + let suffix = '.d.ts'; + + if (format === ts.ModuleKind.CommonJS) { + suffix = '.d.cts'; + } + + if (format === ts.ModuleKind.ESNext) { + suffix = '.d.mts'; + } + + return declarationPath(filename, cwd, suffix); + }; +} + +export function importPath(from: string, to: string) { + const relative = slash(path.relative(path.dirname(from), to)) + .replace(/\.d\.mts$/, '.mjs') + .replace(/\.d\.cts$/, '.cjs') + .replace(/\.d\.ts$/, '.js'); + + return relative.startsWith('.') ? relative : `./${relative}`; +} diff --git a/packages/arui-scripts/src/commands/util/module-contracts/declaration-references.ts b/packages/arui-scripts/src/commands/util/module-contracts/declaration-references.ts new file mode 100644 index 00000000..b6ca910a --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/declaration-references.ts @@ -0,0 +1,169 @@ +import path from 'path'; + +import type * as TypeScript from 'typescript'; + +import { packageForFile } from './contract-dependencies'; +import { slash } from './declaration-paths'; +import { type EmittedDeclaration } from './emit-declarations'; + +export type DeclarationReferences = { + /** Ambient-декларации проекта, на символы которых ссылается файл. */ + declarations: Set; + /** Файлы импортируемых пакетов, чьи глобальные типы использует файл. */ + globalTypes: Set; +}; + +/** Объявление в глобальной области: в скрипте или в `declare global`, но не в `declare module "x"`. */ +function isGlobalDeclaration(ts: typeof TypeScript, declaration: TypeScript.Declaration) { + for (let node = declaration.parent; node; node = node.parent) { + if (ts.isModuleDeclaration(node)) { + if (node.flags & ts.NodeFlags.GlobalAugmentation) return true; + if (ts.isStringLiteral(node.name)) return false; + } + } + + return !ts.isExternalModule(declaration.getSourceFile()); +} + +/** + * Пакеты, которые импортирует код проекта. Их глобальные типы (как JSX в `@types/react`) + * приходят к хосту вместе с импортом. Пакеты только из `types` — окружение поставщика: + * их глобалы не публикуются, и декларации с ними не проходят проверку. + */ +function getImportedPackages( + ts: typeof TypeScript, + program: TypeScript.Program, + host: TypeScript.ModuleResolutionHost, +) { + const options = program.getCompilerOptions(); + const names = new Set(); + + program + .getSourceFiles() + .filter( + (file) => + !program.isSourceFileFromExternalLibrary(file) && + !program.isSourceFileDefaultLibrary(file), + ) + .forEach((file) => { + ts.preProcessFile(file.text, true, true).importedFiles.forEach(({ fileName }) => { + const resolved = ts.resolveModuleName( + fileName, + file.fileName, + options, + host, + ).resolvedModule; + const owner = + resolved?.isExternalLibraryImport && packageForFile(resolved.resolvedFileName); + + if (owner) names.add(owner.name); + }); + }); + + return names; +} + +export function createDeclarationReferences( + ts: typeof TypeScript, + producer: TypeScript.Program, + declarations: ReadonlyMap, +) { + const bySource = new Map( + Array.from(declarations, ([filename, declaration]) => [ + declaration.source, + { filename, ...declaration }, + ]), + ); + const producerFiles = producer + .getSourceFiles() + .filter((file) => !producer.isSourceFileDefaultLibrary(file)); + const externalFiles = new Set( + producerFiles + .filter((file) => producer.isSourceFileFromExternalLibrary(file)) + .map((file) => file.fileName), + ); + const options = producer.getCompilerOptions(); + const host = ts.createCompilerHost(options, true); + const { getSourceFile } = host; + const importedPackages = getImportedPackages(ts, producer, host); + const isImportedGlobal = (declaration: TypeScript.Declaration) => { + const { fileName } = declaration.getSourceFile(); + const owner = externalFiles.has(fileName) ? packageForFile(fileName) : undefined; + + return !!owner && importedPackages.has(owner.name) && isGlobalDeclaration(ts, declaration); + }; + + // Связываем выпущенные сигнатуры по исходным путям в том же наборе файлов, что у проекта: + // так находятся и ambient-символы проекта, и глобалы пакетов, импорт которых пропал из деклараций. + host.getSourceFile = (filename, languageVersion, onError, shouldCreateNewSourceFile) => { + const emitted = bySource.get(filename); + + return emitted + ? ts.createSourceFile(filename, emitted.text, languageVersion, true, ts.ScriptKind.TS) + : getSourceFile(filename, languageVersion, onError, shouldCreateNewSourceFile); + }; + const program = ts.createProgram( + producerFiles.map((file) => file.fileName), + options, + host, + ); + const checker = program.getTypeChecker(); + + return (sourceFile: string): DeclarationReferences => { + const boundSource = program.getSourceFile(sourceFile); + const references: DeclarationReferences = { + declarations: new Set(), + globalTypes: new Set(), + }; + const visit = (node: TypeScript.Node) => { + if (ts.isIdentifier(node) || ts.isStringLiteral(node)) { + checker.getSymbolAtLocation(node)?.declarations?.forEach((declaration) => { + const owner = declaration.getSourceFile(); + const emitted = bySource.get(owner.fileName); + + if (owner.isDeclarationFile && owner !== boundSource && emitted) { + references.declarations.add(emitted.filename); + } else if (isImportedGlobal(declaration)) { + references.globalTypes.add(owner.fileName); + } + }); + } + ts.forEachChild(node, visit); + }; + + if (boundSource) visit(boundSource); + + return references; + }; +} + +/** Заменяет пути `/// ` по позициям из парсера, не трогая остальной текст. */ +export function rewriteReferencePaths( + ts: typeof TypeScript, + text: string, + rewrite: (fileName: string) => string, +) { + const { referencedFiles } = ts.createSourceFile( + 'references.d.ts', + text, + ts.ScriptTarget.Latest, + ); + + return [...referencedFiles] + .sort((a, b) => b.pos - a.pos) + .reduce( + (result, { pos, end, fileName }) => + `${result.slice(0, pos)}${rewrite(fileName)}${result.slice(end)}`, + text, + ); +} + +export function referencePaths(from: string, targets: Iterable) { + return Array.from( + targets, + (target) => + `/// \n`, + ).join(''); +} diff --git a/packages/arui-scripts/src/commands/util/module-contracts/emit-declarations.ts b/packages/arui-scripts/src/commands/util/module-contracts/emit-declarations.ts new file mode 100644 index 00000000..98d8aa4c --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/emit-declarations.ts @@ -0,0 +1,59 @@ +import type * as TypeScript from 'typescript'; + +export type EmittedDeclaration = { + source: string; + text: string +}; + +export function emitDeclarations( + ts: typeof TypeScript, + program: TypeScript.Program, + declarationPath: (filename: string) => string, +) { + const declarations = new Map(); + const emitted = program.emit(undefined, (_file, text, _bom, _error, sources) => { + const source = sources?.[0]?.fileName; + + if (source) declarations.set(declarationPath(source), { source, text }); + }); + const checker = program.getTypeChecker(); + + program.getSourceFiles().forEach((source) => { + if (source.fileName.endsWith('.json') && !program.isSourceFileFromExternalLibrary(source)) { + const statement = source.statements[0]; + + if (!statement || !ts.isExpressionStatement(statement)) { + throw new Error(`modules.types: не удалось получить тип JSON ${source.fileName}`); + } + const type = checker.typeToTypeNode( + checker.getTypeAtLocation(statement.expression), + undefined, + ts.NodeBuilderFlags.NoTruncation, + ); + + if (!type) { + throw new Error(`modules.types: отсутствует тип JSON ${source.fileName}`); + } + + const text = ts.createPrinter().printNode(ts.EmitHint.Unspecified, type, source); + + declarations.set(declarationPath(source.fileName), { + source: source.fileName, + text: `declare const value: ${text};\nexport = value;\n`, + }); + } else if ( + source.isDeclarationFile && + !program.isSourceFileDefaultLibrary(source) && + !program.isSourceFileFromExternalLibrary(source) + ) { + declarations.set(declarationPath(source.fileName), { + source: source.fileName, + text: source.text, + }); + } + }); + + // JSON may set emitSkipped even when all required TS declarations were emitted. + // The caller checks diagnostics and requires every reachable declaration to exist. + return { declarations, diagnostics: emitted.diagnostics }; +} diff --git a/packages/arui-scripts/src/commands/util/module-contracts/generate-declarations.ts b/packages/arui-scripts/src/commands/util/module-contracts/generate-declarations.ts new file mode 100644 index 00000000..2ffe7cbb --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/generate-declarations.ts @@ -0,0 +1,254 @@ +import { builtinModules } from 'module'; +import path from 'path'; + +import type * as TypeScript from 'typescript'; + +import { createContractDependencies, typeReferenceName } from './contract-dependencies'; +import { createDeclarationPath, importPath, slash } from './declaration-paths'; +import { + createDeclarationReferences, + referencePaths, + rewriteReferencePaths, +} from './declaration-references'; +import { emitDeclarations } from './emit-declarations'; +import { formatDiagnostics } from './project-typescript'; + +export type ModuleDeclarations = { + files: Map; + peerDependencies: Record; +}; + +/** Выпускает замкнутое дерево declarations; не меняет output приложения. */ +export function generateModuleDeclarations({ + ts, + cwd, + tsconfig, + exposes, +}: { + ts: typeof TypeScript; + cwd: string; + tsconfig: string; + exposes: Record; +}): ModuleDeclarations { + const configFile = ts.readConfigFile(tsconfig, ts.sys.readFile); + const parsed = ts.parseJsonConfigFileContent( + configFile.config || {}, + ts.sys, + path.dirname(tsconfig), + undefined, + tsconfig, + ); + const format = (diagnostics: readonly TypeScript.Diagnostic[]) => + formatDiagnostics(ts, cwd, diagnostics); + const configErrors = [...(configFile.error ? [configFile.error] : []), ...parsed.errors]; + + if (configErrors.length) throw new Error(format(configErrors)); + if (parsed.projectReferences?.length) { + throw new Error('modules.types: project references пока не поддерживаются.'); + } + + const options: TypeScript.CompilerOptions = { + ...parsed.options, + declaration: true, + emitDeclarationOnly: true, + noEmit: false, + noEmitOnError: true, + noCheck: false, + // Provider environment types may conflict with the project's DOM/Node versions. + // The exported declaration tree is checked separately with skipLibCheck disabled. + skipLibCheck: true, + declarationMap: false, + incremental: false, + composite: false, + outFile: undefined, + declarationDir: undefined, + tsBuildInfoFile: undefined, + rootDir: cwd, + outDir: path.join(cwd, '.arui-contract-declarations'), + }; + const host = ts.createCompilerHost(options); + const resolveModule = ( + specifier: string, + containingFile: string, + mode?: TypeScript.ResolutionMode, + ) => + ts.resolveModuleName(specifier, containingFile, options, host, undefined, undefined, mode) + .resolvedModule; + const entrySources: Record = {}; + const roots = Object.entries(exposes).map(([id, entry]) => { + const resolved = resolveModule(entry, path.join(cwd, '__entry__.ts')); + + if ( + !resolved || + !/\.(ts|tsx|mts|cts)$/.test(resolved.resolvedFileName) || + /\.d\./.test(resolved.resolvedFileName) + ) { + throw new Error(`modules.types: ${id}: не найдена TypeScript-точка входа ${entry}`); + } + entrySources[id] = resolved.resolvedFileName; + + return resolved.resolvedFileName; + }); + const ambientRoots = parsed.fileNames.filter((file) => /\.d\.(ts|mts|cts)$/.test(file)); + const program = ts.createProgram([...roots, ...ambientRoots], options); + const diagnostics = ts.getPreEmitDiagnostics(program); + + if (diagnostics.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) { + throw new Error(format(diagnostics)); + } + + const declarationPath = createDeclarationPath(ts, program, cwd); + const entries = Object.fromEntries( + Object.entries(entrySources).map(([id, filename]) => [id, declarationPath(filename)]), + ); + const emitted = emitDeclarations(ts, program, declarationPath); + const { declarations } = emitted; + + if (emitted.diagnostics.length) throw new Error(format(emitted.diagnostics)); + + const { peerDependencies, addDependency } = createContractDependencies(); + const files = new Map(); + const typeReferences = new Set(); + const queue = Object.values(entries); + const getDeclarationReferences = createDeclarationReferences(ts, program, declarations); + const addTypeReference = (specifier: string, resolvedFile: string | undefined) => { + typeReferences.add(typeReferenceName(addDependency(specifier, resolvedFile))); + }; + const addNodeTypes = () => + addTypeReference( + '@types/node', + ts.resolveTypeReferenceDirective('node', path.join(cwd, '__entry__.ts'), options, host) + .resolvedTypeReferenceDirective?.resolvedFileName, + ); + + const includeDeclaration = (filename: string) => { + if (files.has(filename)) return; + const declaration = declarations.get(filename); + + if (!declaration) throw new Error(`modules.types: отсутствует декларация ${filename}`); + const original = program.getSourceFile(declaration.source); + const { declarations: references, globalTypes } = getDeclarationReferences( + declaration.source, + ); + + globalTypes.forEach((file) => addTypeReference(file, file)); + queue.push(...references); + const text = rewriteReferencePaths(ts, declaration.text, (reference) => { + const target = declarationPath( + path.resolve(path.dirname(declaration.source), reference), + ); + + queue.push(target); + references.delete(target); + + return slash(path.relative(path.dirname(filename), target)); + }); + const source = ts.createSourceFile(filename, text, ts.ScriptTarget.Latest, true); + const resolveImport = (usage: TypeScript.StringLiteral) => { + const specifier = usage.text; + + if (specifier.startsWith('node:') || builtinModules.includes(specifier)) { + addNodeTypes(); + + return specifier; + } + const mode = original && ts.getModeForUsageLocation(original, usage, options); + const resolved = resolveModule(specifier, declaration.source, mode); + + if (!resolved) return specifier; // Ambient module: проверяется на переносимом output. + if (!resolved.isExternalLibraryImport) { + const target = declarationPath(resolved.resolvedFileName); + + queue.push(target); + references.delete(target); + + return importPath(filename, target); + } + if ( + specifier.startsWith('.') || + path.isAbsolute(specifier) || + specifier.startsWith('#') + ) { + throw new Error( + `modules.types: используйте публичный npm import вместо ${specifier}`, + ); + } + addDependency(specifier, resolved.resolvedFileName); + + return specifier; + }; + const transformed = ts.transform(source, [ + (context) => { + const visit: TypeScript.Visitor = (node) => { + if (ts.isStringLiteral(node)) { + const { parent } = node; + const isModuleSpecifier = + ((ts.isImportDeclaration(parent) || ts.isExportDeclaration(parent)) && + parent.moduleSpecifier === node) || + ts.isExternalModuleReference(parent) || + (ts.isModuleDeclaration(parent) && parent.name === node) || + (ts.isLiteralTypeNode(parent) && ts.isImportTypeNode(parent.parent)); + + if (isModuleSpecifier) + return ts.factory.createStringLiteral(resolveImport(node)); + } + + return ts.visitEachChild(node, visit, context); + }; + + return (node) => ts.visitNode(node, visit) as TypeScript.SourceFile; + }, + ]); + + try { + source.typeReferenceDirectives.forEach((reference) => { + const resolved = ts.resolveTypeReferenceDirective( + reference.fileName, + declaration.source, + options, + host, + ).resolvedTypeReferenceDirective; + + if (resolved) addDependency(reference.fileName, resolved.resolvedFileName); + }); + files.set( + filename, + `${referencePaths(filename, references)}${ts + .createPrinter() + .printFile(transformed.transformed[0])}`, + ); + } finally { + transformed.dispose(); + } + }; + + while (queue.length) { + includeDeclaration(queue.shift() as string); + } + + const references = [...typeReferences] + .sort() + .map((name) => `/// \n`) + .join(''); + + Object.values(entries).forEach((filename) => { + files.set(filename, `${references}${files.get(filename)}`); + }); + files.set( + 'index.d.ts', + `${references}export type ModuleContracts = {\n${Object.entries(entries) + .map( + ([id, filename]) => + ` ${JSON.stringify(id)}: typeof import(${JSON.stringify( + importPath('index.d.ts', filename), + )});`, + ) + .join('\n')}\n};\n`, + ); + files.set( + 'index.d.cts', + 'export type { ModuleContracts } from "./index.js" with { "resolution-mode": "import" };\n', + ); + + return { files, peerDependencies }; +} diff --git a/packages/arui-scripts/src/commands/util/module-contracts/project-typescript.ts b/packages/arui-scripts/src/commands/util/module-contracts/project-typescript.ts new file mode 100644 index 00000000..5af56270 --- /dev/null +++ b/packages/arui-scripts/src/commands/util/module-contracts/project-typescript.ts @@ -0,0 +1,29 @@ +import { createRequire } from 'module'; +import path from 'path'; + +import type * as TypeScript from 'typescript'; + +import { getProjectTypeScript } from '../../../configs/util/typescript'; + +/** Загружает Compiler API из TypeScript проекта; генерации нужен TypeScript 5.x или 6.x. */ +export function requireProjectTypeScript(cwd: string) { + const { version } = getProjectTypeScript(cwd); + + if (![5, 6].includes(Number.parseInt(version, 10))) { + throw new Error('modules.types: генерация требует TypeScript 5.x или 6.x с Compiler API.'); + } + + return createRequire(path.join(cwd, 'package.json'))('typescript') as typeof TypeScript; +} + +export function formatDiagnostics( + ts: typeof TypeScript, + cwd: string, + diagnostics: readonly TypeScript.Diagnostic[], +) { + return ts.formatDiagnosticsWithColorAndContext(diagnostics, { + getCanonicalFileName: (file) => file, + getCurrentDirectory: () => cwd, + getNewLine: () => '\n', + }); +} diff --git a/packages/arui-scripts/src/configs/app-configs/__tests__/validate-module-types.tests.ts b/packages/arui-scripts/src/configs/app-configs/__tests__/validate-module-types.tests.ts new file mode 100644 index 00000000..57f7d710 --- /dev/null +++ b/packages/arui-scripts/src/configs/app-configs/__tests__/validate-module-types.tests.ts @@ -0,0 +1,59 @@ +import { getDefaultAppConfig, getDefaultAppContext } from '../get-defaults'; +import { type AppContextWithConfigs } from '../types'; +import { validateModuleTypes } from '../validate-module-types'; + +describe('validateModuleTypes', () => { + const enabled = (): AppContextWithConfigs => ({ + ...getDefaultAppConfig(), + ...getDefaultAppContext(), + version: '1.2.3', + tsconfig: '/project/tsconfig.json', + modules: { + shared: {}, + exposes: { Widget: './src/widget' }, + types: { packageName: '@team/widget-contracts' }, + }, + }); + + it('accepts an explicit package name and preserves disabled projects', () => { + expect(() => validateModuleTypes(enabled())).not.toThrow(); + expect(() => validateModuleTypes({ ...enabled(), modules: null })).not.toThrow(); + }); + + it('leaves the application version to the build command', () => { + expect(() => validateModuleTypes({ ...enabled(), version: 'next' })).not.toThrow(); + }); + + it('leaves an explicit package version to the build command', () => { + const config = enabled(); + + if (!config.modules) throw new Error('Expected modules'); + config.modules.types = { packageName: '@team/widget-contracts', version: 'next' }; + expect(() => validateModuleTypes(config)).not.toThrow(); + }); + + it.each(['', '../contracts', '@scope', '@Scope/contracts', 'node_modules'])( + 'rejects an invalid npm package name %s', + (packageName) => { + const config = enabled(); + + if (!config.modules) throw new Error('Expected modules'); + config.modules.types = { packageName }; + expect(() => validateModuleTypes(config)).toThrow('packageName'); + }, + ); + + it('requires a TS project and enabled exposes', () => { + expect(() => validateModuleTypes({ ...enabled(), tsconfig: null })).toThrow( + 'tsconfig.json', + ); + expect(() => validateModuleTypes({ ...enabled(), disableModulesSupport: true })).toThrow( + 'modules.exposes', + ); + const config = enabled(); + + if (!config.modules) throw new Error('Expected modules'); + config.modules.exposes = {}; + expect(() => validateModuleTypes(config)).toThrow('modules.exposes'); + }); +}); diff --git a/packages/arui-scripts/src/configs/app-configs/types.ts b/packages/arui-scripts/src/configs/app-configs/types.ts index d90613ea..b0467f85 100644 --- a/packages/arui-scripts/src/configs/app-configs/types.ts +++ b/packages/arui-scripts/src/configs/app-configs/types.ts @@ -111,11 +111,18 @@ export type AppConfigs = { shared: Shared; exposes?: Record; options?: ModuleConfigBase; + // генерация npm пакета типов из modules.exposes + types?: false | ModuleTypesConfig; shareScope?: string; } | null; nodeExternals?: Omit; }; +export type ModuleTypesConfig = { + packageName: string; + version?: string; +}; + export type ModuleConfigBase = { cssPrefix?: false | string; useSeparateBuild?: boolean; diff --git a/packages/arui-scripts/src/configs/app-configs/validate-config.ts b/packages/arui-scripts/src/configs/app-configs/validate-config.ts index 17ff2dff..ea04fedc 100644 --- a/packages/arui-scripts/src/configs/app-configs/validate-config.ts +++ b/packages/arui-scripts/src/configs/app-configs/validate-config.ts @@ -2,9 +2,11 @@ import { getProjectTypeScript } from '../util/typescript'; import { type AppContextWithConfigs } from './types'; import { validateBuildSizeBudgets } from './validate-build-size-budgets'; +import { validateModuleTypes } from './validate-module-types'; export function validateConfig(config: AppContextWithConfigs) { validateBuildSizeBudgets(config.buildSizeBudgets); + validateModuleTypes(config); const tscSettings = (['codeLoader', 'jestCodeTransformer'] as const).filter( (key) => config[key] === 'tsc', diff --git a/packages/arui-scripts/src/configs/app-configs/validate-module-types.ts b/packages/arui-scripts/src/configs/app-configs/validate-module-types.ts new file mode 100644 index 00000000..1c45ebb5 --- /dev/null +++ b/packages/arui-scripts/src/configs/app-configs/validate-module-types.ts @@ -0,0 +1,27 @@ +import { type AppContextWithConfigs } from './types'; + +export function validateModuleTypes(config: AppContextWithConfigs) { + const settings = config.modules?.types; + + if (settings === undefined || settings === false) { + return; + } + + if ( + !settings || + typeof settings.packageName !== 'string' || + settings.packageName.length > 214 || + !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(settings.packageName) || + ['node_modules', 'favicon.ico'].includes(settings.packageName) + ) { + throw new Error('modules.types.packageName: укажите корректное имя npm-пакета.'); + } + + if (config.disableModulesSupport || !Object.keys(config.modules?.exposes || {}).length) { + throw new Error('modules.types: нужны включенные modules.exposes.'); + } + + if (!config.tsconfig) { + throw new Error('modules.types: нужен tsconfig.json проекта'); + } +} diff --git a/packages/arui-scripts/src/index.ts b/packages/arui-scripts/src/index.ts index 0b02fece..bb4ffeb1 100644 --- a/packages/arui-scripts/src/index.ts +++ b/packages/arui-scripts/src/index.ts @@ -1,6 +1,11 @@ export type { OverrideFile } from './configs/util/apply-overrides'; -export type { AppConfigs, CompatModuleConfig, PackageSettings } from './configs/app-configs/types'; +export type { + AppConfigs, + CompatModuleConfig, + PackageSettings, + ModuleTypesConfig, +} from './configs/app-configs/types'; /** * Утилиты сборки docker-образа, привязанные к глобальному конфигу arui-scripts. diff --git a/packages/example-modules/arui-scripts.config.ts b/packages/example-modules/arui-scripts.config.ts index 0b96cfbe..ab508c32 100644 --- a/packages/example-modules/arui-scripts.config.ts +++ b/packages/example-modules/arui-scripts.config.ts @@ -34,6 +34,9 @@ const aruiScriptsConfig: PackageSettings = { }, }, modules: { + types: { + packageName: '@alfalab/example-module-contracts' + }, shared: { react: '^17.0.0', 'react-dom': '^17.0.0', diff --git a/yarn.lock b/yarn.lock index 4f20fb09..4ca75393 100644 --- a/yarn.lock +++ b/yarn.lock @@ -7249,6 +7249,7 @@ __metadata: dependencies: "@alfalab/arui-scripts-artifacts": "workspace:^" "@alfalab/postcss-custom-properties": "npm:^9.1.2" + "@alfalab/scripts-modules": "workspace:*" "@babel/core": "npm:7.29.7" "@babel/plugin-proposal-decorators": "npm:^7.29.7" "@babel/plugin-proposal-export-default-from": "npm:^7.29.7"