@application-kit/kafka 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @application-kit/kafka
 
+## 0.3.0
+
+### Minor Changes
+
+- e9411eb: Спеки-гейты продукта переехали в пакеты: спека теперь — вызов помощника с параметрами продукта, а нарушение приходит ошибкой со списком.
+
+  `ui/testing`: `assertTokensDeclared`. `kafka/testing` (новый вход): `assertConsumerTopicsConsistent`. `authorization/testing` (новый вход): `assertAbilityRegistryConsistent`. `nestjs-vite/static-assets-gate` (новый вход, отдельно от `/testing`, чтобы спеки с фейком рендерера не грузили `vite`): `assertStaticAssetsLayout`. `lint-config` разрешает импорт нового входа `nestjs-vite/static-assets-gate`.
+
+## 0.2.0
+
+### Minor Changes
+
+- 487f5e6: Новый вход `@application-kit/kafka/event-contract` — правила версии контракта события (`versionedQueueName`, `eventVersionOfTopic`, `eventVersionOfHeaders`, `DEFAULT_EVENT_VERSION`, `EVENT_VERSION_HEADER`) без `kafkajs` и `@nestjs/microservices`: производитель события (outbox) берёт имя очереди оттуда и не грузит транспорт в web-процесс. `kafkajs` и `@nestjs/microservices` стали опциональными peers — они нужны только корневому входу. Корень пакета экспортирует то же, что раньше.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -12,6 +12,8 @@ yarn add @application-kit/kafka
 
 Peer-зависимости: `@nestjs/common`, `@nestjs/core`, `@nestjs/microservices`, `kafkajs`, `rxjs`,
 `@libs-for-dev/nestjs-config-module`, `class-transformer`, `class-validator`, `nestjs-pino`.
+`@nestjs/microservices` и `kafkajs` нужны только корневому входу и объявлены опциональными: процессу,
+который берёт лишь `@application-kit/kafka/event-contract`, ставить их не нужно.
 
 Пакет грузится одним экземпляром на процесс: DI-токены — `Symbol()`, и ESM- и CJS-копии разом
 дали бы два набора токенов.
@@ -95,3 +97,24 @@ export class UserConsumer extends ConsumerAbstract {
 потребитель подписывается `eventTopics(queue, version)`, а труба сверяет версию топика
 (`eventVersionOfTopic`) с заголовком `x-event-version` (`eventVersionOfHeaders`) до вызова
 обработчика: сообщение чужой версии уходит в DLQ, не доходя до кода потребителя.
+
+Правила версии живут и отдельным входом `@application-kit/kafka/event-contract` — без `kafkajs`,
+`@nestjs/microservices` и побочных эффектов. Его берёт производитель события (web-процесс, outbox),
+которому транспорт не нужен; корень пакета экспортирует то же самое.
+
+## Гейт реестра топиков
+
+Имя очереди живёт в манифесте модуля, статике `queueName` события, подписке консьюмера литералом и ключе
+`kafka.eventQueues` values, и типом эти носители не связаны. `assertConsumerTopicsConsistent` из входа
+`@application-kit/kafka/testing` читает их как текст и падает со списком расхождений:
+
+```ts
+await assertConsumerTopicsConsistent({
+  chartValuesFile: 'ops/.helm/values-product.yaml',
+  consumerSources: '*/user-interface/consumers/*.ts',
+  eventSources: '**/domain/events/*.event.ts',
+  manifests: CONSUMER_MANIFESTS,
+  modulesDirectory: 'src/modules',
+  rootDirectory: process.cwd(),
+})
+```

package/dist/cjs/event-contract/index.d.ts

@@ -0,0 +1 @@
+export * from './event-contract-version.js';

package/dist/cjs/event-contract/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./event-contract-version.js"), exports);

package/dist/cjs/index.d.ts

@@ -1,7 +1,7 @@
 export * from './configs/index.js';
+export * from './event-contract/index.js';
 export * from './libs/index.js';
 export * from './constants.js';
-export * from './event-contract-version.js';
 export * from './kafka-commit-interceptor.js';
 export * from './kafka-error-handler.js';
 export * from './kafka.module.js';

package/dist/cjs/index.js

@@ -15,9 +15,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./configs/index.js"), exports);
+__exportStar(require("./event-contract/index.js"), exports);
 __exportStar(require("./libs/index.js"), exports);
 __exportStar(require("./constants.js"), exports);
-__exportStar(require("./event-contract-version.js"), exports);
 __exportStar(require("./kafka-commit-interceptor.js"), exports);
 __exportStar(require("./kafka-error-handler.js"), exports);
 __exportStar(require("./kafka.module.js"), exports);

package/dist/cjs/kafka-commit-interceptor.js

@@ -16,7 +16,7 @@ exports.KafkaAutoCommit = exports.KafkaCommitInterceptor = void 0;
 const common_1 = require("@nestjs/common");
 const rxjs_1 = require("rxjs");
 const constants_js_1 = require("./constants.js");
-const event_contract_version_js_1 = require("./event-contract-version.js");
+const event_contract_version_js_1 = require("./event-contract/event-contract-version.js");
 const kafka_error_handler_js_1 = require("./kafka-error-handler.js");
 let KafkaCommitInterceptor = class KafkaCommitInterceptor {
     kafkaErrorHandler;

package/dist/cjs/libs/topic-suffixes.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.eventTopics = void 0;
-const event_contract_version_js_1 = require("../event-contract-version.js");
+const event_contract_version_js_1 = require("../event-contract/event-contract-version.js");
 const RETRY_TOPIC_SUFFIX = 'retry';
 const eventTopics = (queueName, version = event_contract_version_js_1.DEFAULT_EVENT_VERSION) => {
     const baseTopic = `events.${(0, event_contract_version_js_1.versionedQueueName)(queueName, version)}`;

package/dist/cjs/testing/assert-consumer-topics-consistent.d.ts

@@ -0,0 +1,13 @@
+export interface ConsumerTopicsManifestInterface {
+    readonly name: string;
+    readonly queues: readonly string[];
+}
+export interface ConsumerTopicsOptionsInterface {
+    readonly chartValuesFile: string;
+    readonly consumerSources: string;
+    readonly eventSources: string;
+    readonly manifests: readonly ConsumerTopicsManifestInterface[];
+    readonly modulesDirectory: string;
+    readonly rootDirectory: string;
+}
+export declare const assertConsumerTopicsConsistent: (options: ConsumerTopicsOptionsInterface) => Promise<void>;

package/dist/cjs/testing/assert-consumer-topics-consistent.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertConsumerTopicsConsistent = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const EVENT_QUEUE = /static readonly queueName\b[^\n]*'(?<queue>[^\n']+)'/u;
+const SUBSCRIBED_QUEUE = /eventTopics\([^\n]*'(?<queue>[^\n']+)'/gu;
+const CHART_QUEUES_BLOCK = /^ {2}eventQueues:\n(?<block>(?:(?: {4}.*)?\n)*)/mu;
+const CHART_QUEUE = /^ {4}(?<queue>[\w\-.]+):/gmu;
+const readSources = async (directory, pattern) => {
+    const files = await Array.fromAsync((0, promises_1.glob)(pattern, { cwd: directory }));
+    const sources = files.filter((file) => !file.endsWith('.spec.ts'));
+    return Promise.all(sources.map(async (file) => ({
+        file,
+        text: await (0, promises_1.readFile)(node_path_1.default.join(directory, file), 'utf8'),
+    })));
+};
+const missingFrom = (actual, expected) => {
+    const rest = [...actual];
+    return expected.filter((queue) => {
+        const index = rest.indexOf(queue);
+        if (index === -1) {
+            return true;
+        }
+        rest.splice(index, 1);
+        return false;
+    });
+};
+const chartViolations = (values, declared) => {
+    const block = CHART_QUEUES_BLOCK.exec(values)?.groups?.block ?? '';
+    const chartQueues = [...block.matchAll(CHART_QUEUE)].map((match) => match.groups?.queue ?? '');
+    return [
+        ...missingFrom(chartQueues, declared).map((queue) => `очередь ${queue} из манифеста без ключа kafka.eventQueues: автосоздание топиков выключено, консьюмер упадёт`),
+        ...missingFrom(declared, chartQueues).map((queue) => `ключ kafka.eventQueues.${queue} без очереди в манифесте: топик без производителя`),
+    ];
+};
+const queueOf = ({ text }) => EVENT_QUEUE.exec(text)?.groups?.queue;
+const ownerOf = ({ file }) => file.split('/', 1).join('');
+const producedQueues = (events) => {
+    const produced = new Map();
+    for (const event of events) {
+        const queue = queueOf(event);
+        if (queue !== undefined) {
+            produced.set(ownerOf(event), [...produced.get(ownerOf(event)) ?? [], queue]);
+        }
+    }
+    return produced;
+};
+const ownerViolations = (events, manifests) => {
+    const produced = producedQueues(events);
+    const declared = new Map(manifests.map(({ name, queues }) => [name, queues]));
+    const owners = [...new Set([...produced.keys(), ...declared.keys()])];
+    return [
+        ...events.filter((event) => queueOf(event) === undefined).map(({ file }) => `событие без queueName (${file})`),
+        ...owners.flatMap((owner) => {
+            const ownQueues = produced.get(owner) ?? [];
+            const declaredQueues = declared.get(owner) ?? [];
+            return [
+                ...missingFrom(declaredQueues, ownQueues).map((queue) => `модуль ${owner}: очередь ${queue} есть у события, но не в манифесте модуля`),
+                ...missingFrom(ownQueues, declaredQueues).map((queue) => `модуль ${owner}: очередь ${queue} в манифесте без события модуля`),
+            ];
+        }),
+    ];
+};
+const subscriptionViolations = (consumers, declared) => consumers.flatMap(({ file, text }) => [...text.matchAll(SUBSCRIBED_QUEUE)]
+    .map((match) => match.groups?.queue ?? '')
+    .filter((queue) => !declared.includes(queue))
+    .map((queue) => `подписка на очередь ${queue} вне реестра: топик никто не производит (${file})`));
+const assertConsumerTopicsConsistent = async (options) => {
+    const { chartValuesFile, consumerSources, eventSources, manifests, modulesDirectory, rootDirectory } = options;
+    const directory = node_path_1.default.join(rootDirectory, modulesDirectory);
+    const [values, events, consumers] = await Promise.all([
+        (0, promises_1.readFile)(node_path_1.default.join(rootDirectory, chartValuesFile), 'utf8'),
+        readSources(directory, eventSources),
+        readSources(directory, consumerSources),
+    ]);
+    const declared = manifests.flatMap(({ queues }) => queues);
+    const emptyPatterns = [
+        ...events.length === 0 ? [`шаблон событий ${eventSources} не нашёл файлов`] : [],
+        ...consumers.length === 0 ? [`шаблон консьюмеров ${consumerSources} не нашёл файлов`] : [],
+    ];
+    const violations = [
+        ...emptyPatterns,
+        ...chartViolations(values, declared),
+        ...ownerViolations(events, manifests),
+        ...subscriptionViolations(consumers, declared),
+    ];
+    if (violations.length > 0) {
+        throw new Error(`Гейт реестра топиков Kafka:\n${violations.join('\n')}`);
+    }
+};
+exports.assertConsumerTopicsConsistent = assertConsumerTopicsConsistent;

package/dist/cjs/testing/index.d.ts

@@ -0,0 +1 @@
+export * from './assert-consumer-topics-consistent.js';

package/dist/cjs/testing/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./assert-consumer-topics-consistent.js"), exports);

package/dist/esm/event-contract/index.d.ts

@@ -0,0 +1 @@
+export * from './event-contract-version.js';

package/dist/esm/event-contract/index.js

@@ -0,0 +1 @@
+export * from './event-contract-version.js';

package/dist/esm/index.d.ts

@@ -1,7 +1,7 @@
 export * from './configs/index.js';
+export * from './event-contract/index.js';
 export * from './libs/index.js';
 export * from './constants.js';
-export * from './event-contract-version.js';
 export * from './kafka-commit-interceptor.js';
 export * from './kafka-error-handler.js';
 export * from './kafka.module.js';

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 export * from './configs/index.js';
+export * from './event-contract/index.js';
 export * from './libs/index.js';
 export * from './constants.js';
-export * from './event-contract-version.js';
 export * from './kafka-commit-interceptor.js';
 export * from './kafka-error-handler.js';
 export * from './kafka.module.js';

package/dist/esm/kafka-commit-interceptor.js

@@ -13,7 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { applyDecorators, BadRequestException, Inject, Injectable, UseInterceptors, } from '@nestjs/common';
 import { catchError, of, tap, throwError } from 'rxjs';
 import { KAFKA_LOGGER } from './constants.js';
-import { eventVersionOfHeaders, eventVersionOfTopic } from './event-contract-version.js';
+import { eventVersionOfHeaders, eventVersionOfTopic } from './event-contract/event-contract-version.js';
 import { KafkaErrorHandler } from './kafka-error-handler.js';
 let KafkaCommitInterceptor = class KafkaCommitInterceptor {
     kafkaErrorHandler;

package/dist/esm/libs/topic-suffixes.js

@@ -1,4 +1,4 @@
-import { DEFAULT_EVENT_VERSION, versionedQueueName } from '../event-contract-version.js';
+import { DEFAULT_EVENT_VERSION, versionedQueueName } from '../event-contract/event-contract-version.js';
 const RETRY_TOPIC_SUFFIX = 'retry';
 export const eventTopics = (queueName, version = DEFAULT_EVENT_VERSION) => {
     const baseTopic = `events.${versionedQueueName(queueName, version)}`;

package/dist/esm/testing/assert-consumer-topics-consistent.d.ts

@@ -0,0 +1,13 @@
+export interface ConsumerTopicsManifestInterface {
+    readonly name: string;
+    readonly queues: readonly string[];
+}
+export interface ConsumerTopicsOptionsInterface {
+    readonly chartValuesFile: string;
+    readonly consumerSources: string;
+    readonly eventSources: string;
+    readonly manifests: readonly ConsumerTopicsManifestInterface[];
+    readonly modulesDirectory: string;
+    readonly rootDirectory: string;
+}
+export declare const assertConsumerTopicsConsistent: (options: ConsumerTopicsOptionsInterface) => Promise<void>;

package/dist/esm/testing/assert-consumer-topics-consistent.js

@@ -0,0 +1,88 @@
+import { glob, readFile } from 'node:fs/promises';
+import path from 'node:path';
+const EVENT_QUEUE = /static readonly queueName\b[^\n]*'(?<queue>[^\n']+)'/u;
+const SUBSCRIBED_QUEUE = /eventTopics\([^\n]*'(?<queue>[^\n']+)'/gu;
+const CHART_QUEUES_BLOCK = /^ {2}eventQueues:\n(?<block>(?:(?: {4}.*)?\n)*)/mu;
+const CHART_QUEUE = /^ {4}(?<queue>[\w\-.]+):/gmu;
+const readSources = async (directory, pattern) => {
+    const files = await Array.fromAsync(glob(pattern, { cwd: directory }));
+    const sources = files.filter((file) => !file.endsWith('.spec.ts'));
+    return Promise.all(sources.map(async (file) => ({
+        file,
+        text: await readFile(path.join(directory, file), 'utf8'),
+    })));
+};
+const missingFrom = (actual, expected) => {
+    const rest = [...actual];
+    return expected.filter((queue) => {
+        const index = rest.indexOf(queue);
+        if (index === -1) {
+            return true;
+        }
+        rest.splice(index, 1);
+        return false;
+    });
+};
+const chartViolations = (values, declared) => {
+    const block = CHART_QUEUES_BLOCK.exec(values)?.groups?.block ?? '';
+    const chartQueues = [...block.matchAll(CHART_QUEUE)].map((match) => match.groups?.queue ?? '');
+    return [
+        ...missingFrom(chartQueues, declared).map((queue) => `очередь ${queue} из манифеста без ключа kafka.eventQueues: автосоздание топиков выключено, консьюмер упадёт`),
+        ...missingFrom(declared, chartQueues).map((queue) => `ключ kafka.eventQueues.${queue} без очереди в манифесте: топик без производителя`),
+    ];
+};
+const queueOf = ({ text }) => EVENT_QUEUE.exec(text)?.groups?.queue;
+const ownerOf = ({ file }) => file.split('/', 1).join('');
+const producedQueues = (events) => {
+    const produced = new Map();
+    for (const event of events) {
+        const queue = queueOf(event);
+        if (queue !== undefined) {
+            produced.set(ownerOf(event), [...produced.get(ownerOf(event)) ?? [], queue]);
+        }
+    }
+    return produced;
+};
+const ownerViolations = (events, manifests) => {
+    const produced = producedQueues(events);
+    const declared = new Map(manifests.map(({ name, queues }) => [name, queues]));
+    const owners = [...new Set([...produced.keys(), ...declared.keys()])];
+    return [
+        ...events.filter((event) => queueOf(event) === undefined).map(({ file }) => `событие без queueName (${file})`),
+        ...owners.flatMap((owner) => {
+            const ownQueues = produced.get(owner) ?? [];
+            const declaredQueues = declared.get(owner) ?? [];
+            return [
+                ...missingFrom(declaredQueues, ownQueues).map((queue) => `модуль ${owner}: очередь ${queue} есть у события, но не в манифесте модуля`),
+                ...missingFrom(ownQueues, declaredQueues).map((queue) => `модуль ${owner}: очередь ${queue} в манифесте без события модуля`),
+            ];
+        }),
+    ];
+};
+const subscriptionViolations = (consumers, declared) => consumers.flatMap(({ file, text }) => [...text.matchAll(SUBSCRIBED_QUEUE)]
+    .map((match) => match.groups?.queue ?? '')
+    .filter((queue) => !declared.includes(queue))
+    .map((queue) => `подписка на очередь ${queue} вне реестра: топик никто не производит (${file})`));
+export const assertConsumerTopicsConsistent = async (options) => {
+    const { chartValuesFile, consumerSources, eventSources, manifests, modulesDirectory, rootDirectory } = options;
+    const directory = path.join(rootDirectory, modulesDirectory);
+    const [values, events, consumers] = await Promise.all([
+        readFile(path.join(rootDirectory, chartValuesFile), 'utf8'),
+        readSources(directory, eventSources),
+        readSources(directory, consumerSources),
+    ]);
+    const declared = manifests.flatMap(({ queues }) => queues);
+    const emptyPatterns = [
+        ...events.length === 0 ? [`шаблон событий ${eventSources} не нашёл файлов`] : [],
+        ...consumers.length === 0 ? [`шаблон консьюмеров ${consumerSources} не нашёл файлов`] : [],
+    ];
+    const violations = [
+        ...emptyPatterns,
+        ...chartViolations(values, declared),
+        ...ownerViolations(events, manifests),
+        ...subscriptionViolations(consumers, declared),
+    ];
+    if (violations.length > 0) {
+        throw new Error(`Гейт реестра топиков Kafka:\n${violations.join('\n')}`);
+    }
+};

package/dist/esm/testing/index.d.ts

@@ -0,0 +1 @@
+export * from './assert-consumer-topics-consistent.js';

package/dist/esm/testing/index.js

@@ -0,0 +1 @@
+export * from './assert-consumer-topics-consistent.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@application-kit/kafka",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Kafka-транспорт для NestJS: консьюмер-процесс с heartbeat, auto-commit, retry/DLQ и контракт версии события",
   "keywords": [
     "consumer",
@@ -32,7 +32,27 @@
         "default": "./dist/cjs/index.js"
       }
     },
-    "./package.json": "./package.json"
+    "./event-contract": {
+      "import": {
+        "types": "./dist/esm/event-contract/index.d.ts",
+        "default": "./dist/esm/event-contract/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/event-contract/index.d.ts",
+        "default": "./dist/cjs/event-contract/index.js"
+      }
+    },
+    "./package.json": "./package.json",
+    "./testing": {
+      "import": {
+        "types": "./dist/esm/testing/index.d.ts",
+        "default": "./dist/esm/testing/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/testing/index.d.ts",
+        "default": "./dist/cjs/testing/index.js"
+      }
+    }
   },
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -41,7 +61,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
+    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src --entry-only=testing && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
     "lint:tsc": "tsc --noEmit --pretty --project .",
     "test:mutation": "stryker run",
     "test:unit": "vitest run"
@@ -76,6 +96,14 @@
     "nestjs-pino": "^4.6.1",
     "rxjs": "^7.8.0"
   },
+  "peerDependenciesMeta": {
+    "@nestjs/microservices": {
+      "optional": true
+    },
+    "kafkajs": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=24"
   },