ddd-ts-kit 0.0.0-stage → 0.1.0

package/dist/check/events/event-declarations.js

@@ -0,0 +1,37 @@
+import { callEnd } from '../text/call-end.js';
+import { isTypeLiteral } from './is-type-literal.js';
+const DECLARATION = /(?<![\w$.])defineIntegrationEvent\s*(?:<[^<>()]*>)?\s*\(/g;
+const PAYLOAD_KEY = /(?<![\w$.])payload\s*[:,}]/;
+const VERSION_KEY = /(?<![\w$.])version\s*:\s*(\d+)/;
+/** The `defineIntegrationEvent({ ... })` calls found in a source. */
+export function eventDeclarations(file) {
+    const { code } = file.scan;
+    return [...code.matchAll(DECLARATION)].map((match) => {
+        const argumentsStart = match.index + match[0].length;
+        const end = callEnd(code, argumentsStart);
+        const body = code.slice(match.index, end);
+        return {
+            start: match.index,
+            end,
+            type: typeOf(file, argumentsStart, end),
+            version: VERSION_KEY.exec(body)?.[1] ?? '?',
+            hasPayload: PAYLOAD_KEY.test(body),
+        };
+    });
+}
+function typeOf(file, argumentsStart, end) {
+    const { code, strings } = file.scan;
+    const type = strings.find((literal) => {
+        if (literal.start < argumentsStart || literal.start >= end || !isTypeLiteral(file, literal.start)) {
+            return false;
+        }
+        // Directly in the options object: one brace deep, not inside a nested call.
+        const before = code.slice(argumentsStart, literal.start);
+        return count(before, '{') - count(before, '}') === 1 && count(before, '(') === count(before, ')');
+    });
+    return type === undefined ? undefined : { value: type.value, line: type.line };
+}
+function count(text, char) {
+    return text.split(char).length - 1;
+}
+//# sourceMappingURL=event-declarations.js.map

package/dist/check/events/event-declarations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-declarations.js","sourceRoot":"","sources":["../../../src/check/events/event-declarations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,MAAM,WAAW,GAAG,2DAA2D,CAAC;AAChF,MAAM,WAAW,GAAG,4BAA4B,CAAC;AACjD,MAAM,WAAW,GAAG,gCAAgC,CAAC;AAWrD,qEAAqE;AACrE,MAAM,UAAU,iBAAiB,CAAC,IAAgB;IAChD,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;IAE3B,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACnD,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACrD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAE1C,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,GAAG;YACH,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,CAAC;YACvC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG;YAC3C,UAAU,EAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;SACnC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,MAAM,CAAC,IAAgB,EAAE,cAAsB,EAAE,GAAW;IACnE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC;IAEpC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QACpC,IAAI,OAAO,CAAC,KAAK,GAAG,cAAc,IAAI,OAAO,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAClG,OAAO,KAAK,CAAC;QACf,CAAC;QAED,4EAA4E;QAC5E,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAEzD,OAAO,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpG,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;AACjF,CAAC;AAED,SAAS,KAAK,CAAC,IAAY,EAAE,IAAY;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACrC,CAAC"}

package/dist/check/events/in-declaration.d.ts

@@ -0,0 +1,3 @@
+import type { EventDeclaration } from './event-declarations.js';
+export declare function inDeclaration(declarations: readonly EventDeclaration[], offset: number): boolean;
+//# sourceMappingURL=in-declaration.d.ts.map

package/dist/check/events/in-declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-declaration.d.ts","sourceRoot":"","sources":["../../../src/check/events/in-declaration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,wBAAgB,aAAa,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhG"}

package/dist/check/events/in-declaration.js

@@ -0,0 +1,4 @@
+export function inDeclaration(declarations, offset) {
+    return declarations.some((declaration) => offset > declaration.start && offset < declaration.end);
+}
+//# sourceMappingURL=in-declaration.js.map

package/dist/check/events/in-declaration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-declaration.js","sourceRoot":"","sources":["../../../src/check/events/in-declaration.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,aAAa,CAAC,YAAyC,EAAE,MAAc;IACrF,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,KAAK,IAAI,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AACpG,CAAC"}

package/dist/check/events/is-type-literal.d.ts

@@ -0,0 +1,4 @@
+import type { SourceFile } from '../model/source-file.js';
+/** True when the string literal starting at `start` is the value of a `type` key. */
+export declare function isTypeLiteral(file: SourceFile, start: number): boolean;
+//# sourceMappingURL=is-type-literal.d.ts.map

package/dist/check/events/is-type-literal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-type-literal.d.ts","sourceRoot":"","sources":["../../../src/check/events/is-type-literal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAI1D,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtE"}

package/dist/check/events/is-type-literal.js

@@ -0,0 +1,6 @@
+const TYPE_KEY = /(?<![\w$.])type\s*\??\s*:\s*$/;
+/** True when the string literal starting at `start` is the value of a `type` key. */
+export function isTypeLiteral(file, start) {
+    return TYPE_KEY.test(file.scan.code.slice(Math.max(0, start - 40), start));
+}
+//# sourceMappingURL=is-type-literal.js.map

package/dist/check/events/is-type-literal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-type-literal.js","sourceRoot":"","sources":["../../../src/check/events/is-type-literal.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG,+BAA+B,CAAC;AAEjD,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,IAAgB,EAAE,KAAa;IAC3D,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AAC7E,CAAC"}

package/dist/check/events/name-of-event-class.d.ts

@@ -0,0 +1,4 @@
+import type { SourceFile } from '../model/source-file.js';
+/** The name written in the body of the class `className`, when the file declares that class and names it with a literal. */
+export declare function nameOfEventClass(file: SourceFile, className: string): string | undefined;
+//# sourceMappingURL=name-of-event-class.d.ts.map

package/dist/check/events/name-of-event-class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-of-event-class.d.ts","sourceRoot":"","sources":["../../../src/check/events/name-of-event-class.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,4HAA4H;AAC5H,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASxF"}

package/dist/check/events/name-of-event-class.js

@@ -0,0 +1,11 @@
+import { domainEventNames } from './domain-event-names.js';
+/** The name written in the body of the class `className`, when the file declares that class and names it with a literal. */
+export function nameOfEventClass(file, className) {
+    const declared = file.structure.classes.find((candidate) => candidate.name === className);
+    if (declared === undefined) {
+        return undefined;
+    }
+    return domainEventNames(file).find((literal) => literal.start > declared.start && literal.start < declared.end)
+        ?.value;
+}
+//# sourceMappingURL=name-of-event-class.js.map

package/dist/check/events/name-of-event-class.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"name-of-event-class.js","sourceRoot":"","sources":["../../../src/check/events/name-of-event-class.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,4HAA4H;AAC5H,MAAM,UAAU,gBAAgB,CAAC,IAAgB,EAAE,SAAiB;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAE1F,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC;QAC7G,EAAE,KAAK,CAAC;AACZ,CAAC"}

package/dist/check/explain/authz-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from '../model/rule-doc.js';
+export declare const AUTHZ_DOCS: Readonly<Record<string, RuleDoc>>;
+//# sourceMappingURL=authz-docs.d.ts.map

package/dist/check/explain/authz-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-docs.d.ts","sourceRoot":"","sources":["../../../src/check/explain/authz-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4CxD,CAAC"}

package/dist/check/explain/authz-docs.js

@@ -0,0 +1,46 @@
+export const AUTHZ_DOCS = {
+    'authz/declared': {
+        why: 'A use case nobody thought about is reachable by everybody. Declaring the permission next to the registration, or declaring the use case public, makes the decision visible in review and lets the bus middleware refuse everything else. The same holds for a route: its security is part of the contract, not a default. The route type enforces it already (`defineRoute` does not compile without `security` and refuses an empty list); this rule stays as the net for a definition built loosely, from an untyped object or a cast. On a message class, @Requires(...) or @Public() of @ddd-ts-kit/kernel/declarations is the declaration, in any project; in the declared style there is no registration to read, so a command or query class carrying neither is reported.',
+        bad: `builder.command(VoidInvoiceCommand).handledBy(VoidInvoiceHandler, [InvoiceRepository]);
+defineRoute({ method: 'POST', path: '/invoices/:id/void' }, handler);
+// application/commands/void-invoice/void-invoice.command.ts, declared style
+export class VoidInvoiceCommand extends AuthorizedCommand<void> {}`,
+        good: `builder.command(VoidInvoiceCommand).requires(billingPermissions['invoice.void']).handledBy(VoidInvoiceHandler, [InvoiceRepository]);
+builder.query(GetCatalogQuery).public().handledBy(GetCatalogHandler, [CatalogReader]);
+defineRoute({ method: 'POST', path: '/invoices/:id/void', security: ['bearer'] }, handler);
+// application/commands/void-invoice/void-invoice.command.ts, declared style
+@Requires(billingPermissions['invoice.void'])
+export class VoidInvoiceCommand extends AuthorizedCommand<void> {}`,
+    },
+    'authz/in-application': {
+        why: 'A right decided in a route is skipped by every other entry point: a consumer, a job, another route. Decided in an adapter or in an aggregate, it is invisible and tied to one authorization model. In the application layer, behind the Authorizer port, every right is declared once, tested once, and changing from roles to policies or relationships changes an adapter only. A route keeps the request glue of @ddd-ts-kit/auth (actorOf, sessionOf, resolveSession, a SessionAuthenticator); the domain sees neither the Actor, the Session nor the ExecutionContext. The access decorators (Requires, Public, Policy of @ddd-ts-kit/kernel/declarations) and the access ports of @ddd-ts-kit/auth (Access, PolicyAccess) are how the application layer says it: they are imported in application/ and refused in presentation/, infrastructure/ and domain/.',
+        bad: `// presentation/http/void-invoice.route.ts
+if (!context.principal.roles.includes('admin')) {
+  return { status: 403 };
+}
+// presentation/http/void-invoice.route.ts
+import { Requires } from '@ddd-ts-kit/kernel/declarations';`,
+        good: `// presentation/http/void-invoice.route.ts
+await commandBus.execute(new VoidInvoiceCommand(actorOf(context.principal), params.invoiceId));
+// application/commands/void-invoice/void-invoice.handler.ts
+await this.access.authorize(command.actor, billingPermissions['invoice.void'], invoice);
+// application/authorization/only-issuer-voids.policy.ts
+@Policy(billingPermissions['invoice.void'], { name: 'billing.only-issuer-voids' })
+export class OnlyIssuerVoidsPolicy {}`,
+    },
+    'authz/actor-explicit': {
+        why: 'A handler that reads "the current user" from an ambient context depends on something no signature shows: a consumer or a job that forgot to set it fails at run time, and a test has to set a global. With the actor as data of the command, the use case says who acts, and any caller can send it. The ExecutionScope port (and ActorContext, a view of it) is named and read by infrastructure and the platform alone, as a type or as a value in a dependency list, for audit columns, tenant scoping and correlation: stampCreation, stampUpdate and tenantScopeOf belong in a repository adapter.',
+        bad: `// application/commands/void-invoice/void-invoice.handler.ts
+@CommandHandler(VoidInvoiceCommand, [InvoiceRepository, ExecutionScope])
+const actor = this.actors.require();
+const { tenantId } = this.scope.require();
+const stamp = stampCreation(this.scope, this.clock);`,
+        good: `// application/commands/void-invoice/void-invoice.command.ts
+export class VoidInvoiceCommand extends AuthorizedCommand {}
+// application/commands/void-invoice/void-invoice.handler.ts
+const { actor } = command;
+// infrastructure/persistence/drizzle-invoice.repository.ts
+const row = { ...toRow(invoice), ...stampCreation(this.scope, this.clock), ...tenantScopeOf(this.scope) };`,
+    },
+};
+//# sourceMappingURL=authz-docs.js.map

package/dist/check/explain/authz-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-docs.js","sourceRoot":"","sources":["../../../src/check/explain/authz-docs.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAsC;IAC3D,gBAAgB,EAAE;QAChB,GAAG,EAAE,mvBAAmvB;QACxvB,GAAG,EAAE;;;mEAG0D;QAC/D,IAAI,EAAE;;;;;mEAKyD;KAChE;IACD,sBAAsB,EAAE;QACtB,GAAG,EAAE,q0BAAq0B;QAC10B,GAAG,EAAE;;;;;4DAKmD;QACxD,IAAI,EAAE;;;;;;sCAM4B;KACnC;IACD,sBAAsB,EAAE;QACtB,GAAG,EAAE,ykBAAykB;QAC9kB,GAAG,EAAE;;;;qDAI4C;QACjD,IAAI,EAAE;;;;;2GAKiG;KACxG;CACF,CAAC"}

package/dist/check/explain/clean-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from '../model/rule-doc.js';
+export declare const CLEAN_DOCS: Readonly<Record<string, RuleDoc>>;
+//# sourceMappingURL=clean-docs.d.ts.map

package/dist/check/explain/clean-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-docs.d.ts","sourceRoot":"","sources":["../../../src/check/explain/clean-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqCxD,CAAC"}

package/dist/check/explain/clean-docs.js

@@ -0,0 +1,39 @@
+export const CLEAN_DOCS = {
+    'clean/stepdown': {
+        why: 'A reader opens a file to learn what it does, then, if needed, how. With the public members first and each helper below its first caller, the file reads once from top to bottom, like a newspaper article. Helpers on top force the reader to hold details before knowing what they serve.',
+        bad: `function parseLine(line: string) {}
+export function parseFile(text: string) { return text.split('\\n').map(parseLine); }`,
+        good: `export function parseFile(text: string) { return text.split('\\n').map(parseLine); }
+function parseLine(line: string) {}`,
+    },
+    'clean/function-size': {
+        why: 'A long function mixes several levels of abstraction, and its parts can be neither named nor tested alone. More than three parameters usually travel together because they are one concept without a type. Small functions with few arguments are what makes the stepdown order readable. The limits are configurable under `limits`, up to a ceiling: no function is longer than 100 lines, describe callbacks, module files and tests included, and that ceiling is an error whatever the severity of the rule.',
+        bad: `function issue(id: string, customer: string, amount: number, currency: string, dueOn: Date) {}`,
+        good: `function issue(id: string, customer: CustomerId, total: Money) {}`,
+    },
+    'clean/no-commented-out-code': {
+        why: 'Nobody dares to delete commented-out code: it looks important and is never run, compiled or tested. It rots while the code around it changes, and misleads the next reader. Version control keeps every past version without that cost.',
+        bad: `// const total = lines.reduce((sum, line) => sum + line.amount, 0);`,
+        good: `(nothing: the old version is in the history)`,
+    },
+    'clean/no-noise-comment': {
+        why: 'A comment that repeats the name, draws a banner or records who changed what adds reading time and no information, and it drifts from the code it sits on. Comments are kept for what the code cannot say: why, a warning, an external reference.',
+        bad: `/** Gets the order. */
+getOrder(): Order {}
+// ---------- helpers ----------`,
+        good: `// Rounded half-even: required by the tax authority (art. 242).
+round(amount: Money): Money {}`,
+    },
+    'clean/no-escape-hatch': {
+        why: 'any, the non-null assertion and suppressed diagnostics tell the compiler to stop checking, and the error it would have reported comes back at run time, far from its cause. When one is really needed, the written reason is what lets a reviewer judge it.',
+        bad: `const total = (order as any).lines!.length; // @ts-ignore`,
+        good: `if (order.lines === undefined) throw new OrderWithoutLines(order.id);`,
+    },
+    'clean/no-flag-argument': {
+        why: 'A boolean parameter means the method does two things, and the call site (`close(true)`) does not say which. Two methods named after the two intentions are readable at the call site and can each guard their own invariants.',
+        bad: `cancel(refund: boolean): void {}`,
+        good: `cancel(): void {}
+cancelAndRefund(): void {}`,
+    },
+};
+//# sourceMappingURL=clean-docs.js.map

package/dist/check/explain/clean-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean-docs.js","sourceRoot":"","sources":["../../../src/check/explain/clean-docs.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAsC;IAC3D,gBAAgB,EAAE;QAChB,GAAG,EAAE,4RAA4R;QACjS,GAAG,EAAE;qFAC4E;QACjF,IAAI,EAAE;oCAC0B;KACjC;IACD,qBAAqB,EAAE;QACrB,GAAG,EAAE,kfAAkf;QACvf,GAAG,EAAE,gGAAgG;QACrG,IAAI,EAAE,mEAAmE;KAC1E;IACD,6BAA6B,EAAE;QAC7B,GAAG,EAAE,yOAAyO;QAC9O,GAAG,EAAE,qEAAqE;QAC1E,IAAI,EAAE,8CAA8C;KACrD;IACD,wBAAwB,EAAE;QACxB,GAAG,EAAE,kPAAkP;QACvP,GAAG,EAAE;;iCAEwB;QAC7B,IAAI,EAAE;+BACqB;KAC5B;IACD,uBAAuB,EAAE;QACvB,GAAG,EAAE,6PAA6P;QAClQ,GAAG,EAAE,2DAA2D;QAChE,IAAI,EAAE,uEAAuE;KAC9E;IACD,wBAAwB,EAAE;QACxB,GAAG,EAAE,+NAA+N;QACpO,GAAG,EAAE,kCAAkC;QACvC,IAAI,EAAE;2BACiB;KACxB;CACF,CAAC"}

package/dist/check/explain/context-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from '../model/rule-doc.js';
+export declare const CONTEXT_DOCS: Readonly<Record<string, RuleDoc>>;
+//# sourceMappingURL=context-docs.d.ts.map

package/dist/check/explain/context-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-docs.d.ts","sourceRoot":"","sources":["../../../src/check/explain/context-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0C1D,CAAC"}

package/dist/check/explain/context-docs.js

@@ -0,0 +1,44 @@
+export const CONTEXT_DOCS = {
+    'context/published-language-only': {
+        why: 'A bounded context owns its model and must be free to change it. The published language is the only part designed for others; importing anything else couples two models and turns every refactoring into a cross-team negotiation.',
+        bad: `// contexts/shipping/application/...
+import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate.js';`,
+        good: `// contexts/shipping/application/...
+import type { InvoiceIssuedV1 } from '@/contexts/billing/published-language/index.js';`,
+    },
+    'context/declared-relationship': {
+        why: 'The context map is a strategic decision, not a side effect of an import. Declaring the upstream and the pattern keeps the map reviewable and lets the cycle check work.',
+        bad: `// shipping imports billing/published-language, config has "shipping": { "upstreams": [] }`,
+        good: `"shipping": { "classification": "supporting",
+  "upstreams": [{ "context": "billing", "relationship": "published-language" }] }`,
+    },
+    'context/published-language-is-a-contract': {
+        why: 'A contract that re-exports a domain class is no contract: consumers get the internal model and its behaviour through the back door. The published language holds serializable types that are versioned on purpose.',
+        bad: `// published-language/index.ts
+export { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate.js';`,
+        good: `// published-language/invoice-issued.v1.integration-event.ts
+export interface InvoiceIssuedV1Payload { readonly invoiceId: string }`,
+    },
+    'context/no-cycle': {
+        why: 'Two contexts that are upstream of each other are one context with a line drawn through it: neither can be changed, deployed or understood alone. One of them has to be the supplier.',
+        bad: `"billing": { "upstreams": [{ "context": "shipping" }] },
+"shipping": { "upstreams": [{ "context": "billing" }] }`,
+        good: `"billing": { "upstreams": [] },
+"shipping": { "upstreams": [{ "context": "billing" }] }`,
+    },
+    'context/extractable': {
+        why: 'A bounded context is a deployable unit in waiting. Moving one to its own service must change a composition root and adapters, never domain or application code. A module that wires another context, a repository that reads its tables, a handler that loads its aggregates or a map shared through an export all hold only while both live in one process and one database. In the declared style the wiring is written on the classes: a role file that imports a port of another context (anything of its domain/repositories/*.repository.ts or application/ports/*.port.ts) ties the composition of the two, so ports come from the context itself, the kernel, @ddd-ts-kit/auth and the platform.',
+        bad: `// contexts/shipping/infrastructure/persistence/drizzle-parcel.repository.ts
+import { invoices } from '@/contexts/billing/infrastructure/persistence/invoice.schema.js';
+export const cache = new Map<string, Parcel>();
+// contexts/shipping/application/commands/ship-parcel/ship-parcel.handler.ts, declared style
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';`,
+        good: `// contexts/shipping/application/ports/invoice-status.gateway.port.ts
+export abstract class InvoiceStatusGateway { abstract isPaid(invoiceId: string): Promise<boolean>; }
+// contexts/shipping/infrastructure/external/in-process-invoice-status.gateway.ts
+import type { InvoiceStatus } from '@/contexts/billing/published-language/index.js';
+// contexts/shipping/application/commands/ship-parcel/ship-parcel.handler.ts, declared style
+import { InvoiceStatusGateway } from '@/contexts/shipping/application/ports/invoice-status.gateway.port.js';`,
+    },
+};
+//# sourceMappingURL=context-docs.js.map

package/dist/check/explain/context-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-docs.js","sourceRoot":"","sources":["../../../src/check/explain/context-docs.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,YAAY,GAAsC;IAC7D,iCAAiC,EAAE;QACjC,GAAG,EAAE,oOAAoO;QACzO,GAAG,EAAE;qFAC4E;QACjF,IAAI,EAAE;uFAC6E;KACpF;IACD,+BAA+B,EAAE;QAC/B,GAAG,EAAE,yKAAyK;QAC9K,GAAG,EAAE,4FAA4F;QACjG,IAAI,EAAE;kFACwE;KAC/E;IACD,0CAA0C,EAAE;QAC1C,GAAG,EAAE,oNAAoN;QACzN,GAAG,EAAE;qFAC4E;QACjF,IAAI,EAAE;uEAC6D;KACpE;IACD,kBAAkB,EAAE;QAClB,GAAG,EAAE,sLAAsL;QAC3L,GAAG,EAAE;wDAC+C;QACpD,IAAI,EAAE;wDAC8C;KACrD;IACD,qBAAqB,EAAE;QACrB,GAAG,EAAE,0qBAA0qB;QAC/qB,GAAG,EAAE;;;;kGAIyF;QAC9F,IAAI,EAAE;;;;;6GAKmG;KAC1G;CACF,CAAC"}

package/dist/check/explain/events-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from '../model/rule-doc.js';
+export declare const EVENTS_DOCS: Readonly<Record<string, RuleDoc>>;
+//# sourceMappingURL=events-docs.d.ts.map

package/dist/check/explain/events-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-docs.d.ts","sourceRoot":"","sources":["../../../src/check/explain/events-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyEzD,CAAC"}

package/dist/check/explain/events-docs.js

@@ -0,0 +1,75 @@
+export const EVENTS_DOCS = {
+    'events/name-format': {
+        why: 'Event names are routing keys and part of the public contract. A uniform <context>.<aggregate>.<fact> name tells who owns the event and what happened, and never collides across contexts.',
+        bad: `readonly name = 'InvoiceIssued';`,
+        good: `readonly name = 'billing.invoice.issued';`,
+    },
+    'events/defined-in-published-language': {
+        why: 'Integration events are the only way two contexts communicate, so their shape is a public contract. One declaration with a payload schema gives the type, validates what is published and consumed, and feeds the generated catalog and AsyncAPI document. An event described by hand, or declared twice, drifts from what is really sent.',
+        bad: `// application/integration/publishers/invoice-issued.publisher.ts
+const event = { type: 'billing.invoice.issued', version: 1, payload };`,
+        good: `// published-language/invoice-issued.v1.integration-event.ts
+export const invoiceIssuedV1 = defineIntegrationEvent({
+  type: 'billing.invoice.issued', version: 1, payload: zodSchema(z.object({ invoiceId: z.string() })),
+});`,
+    },
+    'events/outbox-required': {
+        why: 'Publishing an event and committing the state change it describes must succeed or fail together. A handler that talks to a broker or a bus publishes events of transactions that roll back, and loses events when the broker is down. Written to the outbox in the transaction of the command, the event is relayed afterwards, whatever the transport.',
+        bad: `// application/commands/issue-invoice/issue-invoice.handler.ts
+import { connect } from 'amqplib';
+// ddd-ts-kit.config.json
+"stack": { "orm": "drizzle", "events": "in-memory" }`,
+        good: `// application/commands/issue-invoice/issue-invoice.handler.ts
+constructor(private readonly publisher: IntegrationEventPublisher) {}
+// platform/platform.module.ts
+eventPublisher: new OutboxPublisher(persistence.outbox),`,
+    },
+    'events/consumer-idempotent': {
+        why: 'Delivery is at least once: a consumer sees the same event again after a retry, a restart or a replay. The processed-event store recognises a redelivery by the pair consumer name and event id, in the transaction of the handler. A consumer without a name, or sharing the name of another, either handles events twice or skips events it never handled. An integration event handler class that carries @IntegrationEventHandler(definition, { consumer }) is named by its declaration and needs no registration; the name is a string literal, and it is unique across declarations and registrations alike.',
+        bad: `// billing.module.ts
+subscriber.subscribe('catalog.product.listed', (event) => productListedHandler.handle(event));
+// application/integration/handlers/product-listed.integration-handler.ts
+@IntegrationEventHandler(productListedV1, { consumer: CONSUMER_NAME }, [CommandBus])`,
+        good: `// billing.module.ts
+builder.on(productListedV1, { consumer: 'billing.product-listed' }).handledBy(ProductListedHandler, [CommandBus]);
+// or, wired by hand
+consume(productListedV1, { consumer: 'billing.product-listed', processed, unitOfWork }, (event) => productListedHandler.handle(event));
+// or declared on the class
+@IntegrationEventHandler(productListedV1, { consumer: 'billing.product-listed' }, [CommandBus])
+export class ProductListedHandler {}`,
+    },
+    'domain-events/dispatched-on-save': {
+        why: 'Domain events leave with the save. Once a repository method that was handed an aggregate resolves, the events the aggregate recorded are dispatched in order, inside the unit of work of the command, so their handlers and the outbox commit or roll back with the state. A handler that pulls the events and dispatches them itself announces them twice or outside the transaction, and a repository adapter that dispatches mixes persistence with wiring. Reported: a call to pullEvents() in application/ or infrastructure/ of a context, and DomainEventDispatcher imported, listed as a dependency or received by a constructor in application/commands, application/queries and a repository adapter. The module file, the tests, the platform and main.ts are left alone.',
+        bad: `// application/commands/issue-invoice/issue-invoice.handler.ts
+@CommandHandler(IssueInvoiceCommand, [InvoiceRepository, DomainEventDispatcher])
+await this.invoices.save(invoice);
+await this.dispatcher.dispatch(invoice.pullEvents());`,
+        good: `// application/commands/issue-invoice/issue-invoice.handler.ts
+@CommandHandler(IssueInvoiceCommand, [InvoiceRepository])
+await this.invoices.save(invoice);
+// a removal that announces an event takes the aggregate
+await this.invoices.remove(invoice);`,
+    },
+    'domain-events/transactional-before-commit': {
+        why: "An effect of a domain event exists only if the state change that recorded the event is committed. A handler that runs before the commit runs inside the transaction, and the commit can still fail after it ran (a deferred constraint, a serialization failure, a lost connection): that is safe only when the rollback undoes everything the handler did, so a before-commit handler has transactional effects only. Judged: every production class of application/event-handlers/*.event-handler.ts and application/integration/publishers/*.publisher.ts, and any class carrying @DomainEventHandler. Its phase is after-commit when its decorator says phase: 'after-commit', or, without a decorator, when every .on(..) of <context>.module.ts whose callback mentions it has a third argument holding phase: 'after-commit'; otherwise it is before-commit. Its dependencies are the names of its dependency list, of .toClass(Handler, [..]) and the types of its constructor parameters, resolved through the imports. Before the commit it may depend on the domain/ of its context, on the kernel ports except Cache, Lock, RateLimiter, JobScheduler and EventBus, on @ddd-ts-kit/auth, on application helpers of its context, and on a port of application/ports/ only when it is a persistence port: at least one production class implements it under infrastructure/persistence/ and none anywhere else under infrastructure/. Refused: those five kernel ports, any other port of application/ports/, anything of infrastructure/, of another context, of the platform or of another package. An after-commit handler is refused IntegrationEventPublisher alone: after the commit nothing makes the outbox row atomic with a state change, so it sends a command instead.",
+        bad: `// application/event-handlers/invoice-issued.event-handler.ts
+// Mailer is implemented under infrastructure/external/: the mail leaves even when the commit fails
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued' }, [InvoiceRepository, Mailer, Cache])
+// after the commit the outbox row would be written in no transaction
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued', phase: 'after-commit' }, [IntegrationEventPublisher])`,
+        good: `// application/event-handlers/invoice-issued.event-handler.ts: repositories, persistence ports, buses
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued' }, [InvoiceRepository, CommandBus])
+// an effect that may be lost on a crash runs after the commit, at most once
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued', phase: 'after-commit' }, [Cache])
+// explicit style, in billing.module.ts
+platform.domainEvents.on('billing.invoice.issued', async (event) => {
+  if (event instanceof InvoiceIssued) {
+    await invoiceIssuedEventHandler.handle(event);
+  }
+}, { phase: 'after-commit' });
+// an effect that must not be lost: a publisher writes to the outbox, the handler of that event does the work
+@DomainEventHandler(InvoiceIssued, { name: 'billing.invoice.issued' }, [IntegrationEventPublisher, IdGenerator])
+export class InvoiceIssuedPublisher {}`,
+    },
+};
+//# sourceMappingURL=events-docs.js.map

package/dist/check/explain/events-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-docs.js","sourceRoot":"","sources":["../../../src/check/explain/events-docs.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,WAAW,GAAsC;IAC5D,oBAAoB,EAAE;QACpB,GAAG,EAAE,2LAA2L;QAChM,GAAG,EAAE,kCAAkC;QACvC,IAAI,EAAE,2CAA2C;KAClD;IACD,sCAAsC,EAAE;QACtC,GAAG,EAAE,2UAA2U;QAChV,GAAG,EAAE;uEAC8D;QACnE,IAAI,EAAE;;;IAGN;KACD;IACD,wBAAwB,EAAE;QACxB,GAAG,EAAE,wVAAwV;QAC7V,GAAG,EAAE;;;qDAG4C;QACjD,IAAI,EAAE;;;yDAG+C;KACtD;IACD,4BAA4B,EAAE;QAC5B,GAAG,EAAE,mlBAAmlB;QACxlB,GAAG,EAAE;;;qFAG4E;QACjF,IAAI,EAAE;;;;;;qCAM2B;KAClC;IACD,kCAAkC,EAAE;QAClC,GAAG,EAAE,svBAAsvB;QAC3vB,GAAG,EAAE;;;sDAG6C;QAClD,IAAI,EAAE;;;;qCAI2B;KAClC;IACD,2CAA2C,EAAE;QAC3C,GAAG,EAAE,8rDAA8rD;QACnsD,GAAG,EAAE;;;;2HAIkH;QACvH,IAAI,EAAE;;;;;;;;;;;;uCAY6B;KACpC;CACF,CAAC"}

package/dist/check/explain/imports-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from '../model/rule-doc.js';
+export declare const IMPORTS_DOCS: Readonly<Record<string, RuleDoc>>;
+//# sourceMappingURL=imports-docs.d.ts.map

package/dist/check/explain/imports-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports-docs.d.ts","sourceRoot":"","sources":["../../../src/check/explain/imports-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA6B1D,CAAC"}

package/dist/check/explain/imports-docs.js

@@ -0,0 +1,31 @@
+export const IMPORTS_DOCS = {
+    'imports/alias-only': {
+        why: 'An alias names a file from the root of the project: the import reads the same from every file, says which context and which layer it reaches without counting "../", and does not change when the importing file moves. One way of writing an import also means one thing to review and one thing for the boundary rules to read: the checker, ESLint and dependency-cruiser resolve an alias exactly as they resolve a relative path, so no boundary is crossed by choosing the other spelling. The rule holds under the source root, test/ and scripts/, the same directory included, for import, export ... from and import(). The alias is declared once, under "paths" in tsconfig.json, and the build rewrites it into a relative path in the compiled output, which runs with plain `node`. An alias path with a "." or ".." segment is refused too, since it could name a file outside its directory. The compiler reports an alias that names no file; a JavaScript file at the project root (a config, a migration) is not judged. ESLint fixes the import (`eslint --fix`).',
+        bad: `// src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
+import { Invoice } from '../../../domain/aggregates/invoice.aggregate.js';
+import { IssueInvoiceCommand } from './issue-invoice.command.js';`,
+        good: `// src/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.ts
+import { IssueInvoiceCommand } from '@/contexts/billing/application/commands/issue-invoice/issue-invoice.command.js';
+import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate.js';
+// test/e2e/issue-invoice.e2e.spec.ts
+import { startApplication } from '$test/e2e/support/start-application.js';`,
+    },
+    'imports/alias-declared': {
+        why: 'An alias is declared in one place and resolved by many tools: the compiler, the dev runner, the test runner, ESLint, the checker, dependency-cruiser, knip, and the build that makes the output runnable. If two of them disagree, the type check passes on one file while production loads another, or a boundary rule stops seeing an import. So there is one source a person edits, "importAlias" in ddd-ts-kit.config.json, and one declaration derived from it that the tools read, "paths" in tsconfig.json. Node reads neither: the compiler emits an alias as it was written, so `ddd-ts-kit build-aliases` rewrites each one into a relative path after the compiler, and the output runs with plain `node`. The rule compares "paths" (tsconfig.json and tsconfig.build.json) with "importAlias", refuses a second entry under an alias, a "baseUrl" and a knip "paths"; checks that vitest and dependency-cruiser read tsconfig and that jest, which does not, repeats the same mapping; reports a script that compiles without the rewrite step and a tsx script under another tsconfig. An alias is "@/" or "$<name>/": neither can be the name of a package, so no installed dependency can ever take the place of a file of the project; "#<name>/" (a Node subpath import) and "@<name>/" (the name of a scope) are refused.',
+        bad: `// ddd-ts-kit.config.json
+"importAlias": "@/"
+// tsconfig.json
+"paths": { "@/*": ["./dist/src/*"] }
+// package.json
+"build": "tsc -p tsconfig.build.json"`,
+        good: `// ddd-ts-kit.config.json
+"importAlias": "@/"
+// tsconfig.json
+"paths": { "@/*": ["./src/*"], "$test/*": ["./test/*"], "$scripts/*": ["./scripts/*"] }
+// package.json
+"build": "tsc -p tsconfig.build.json && ddd-ts-kit build-aliases"
+// vitest.config.ts
+resolve: { tsconfigPaths: true }`,
+    },
+};
+//# sourceMappingURL=imports-docs.js.map

package/dist/check/explain/imports-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imports-docs.js","sourceRoot":"","sources":["../../../src/check/explain/imports-docs.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,YAAY,GAAsC;IAC7D,oBAAoB,EAAE;QACpB,GAAG,EAAE,whCAAwhC;QAC7hC,GAAG,EAAE;;kEAEyD;QAC9D,IAAI,EAAE;;;;2EAIiE;KACxE;IACD,wBAAwB,EAAE;QACxB,GAAG,EAAE,8wCAA8wC;QACnxC,GAAG,EAAE;;;;;sCAK6B;QAClC,IAAI,EAAE;;;;;;;iCAOuB;KAC9B;CACF,CAAC"}

package/dist/check/explain/language-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from '../model/rule-doc.js';
+export declare const LANGUAGE_DOCS: Readonly<Record<string, RuleDoc>>;
+//# sourceMappingURL=language-docs.d.ts.map

package/dist/check/explain/language-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-docs.d.ts","sourceRoot":"","sources":["../../../src/check/explain/language-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4B3D,CAAC"}

package/dist/check/explain/language-docs.js

@@ -0,0 +1,30 @@
+export const LANGUAGE_DOCS = {
+    'language/glossary-term': {
+        why: 'The ubiquitous language is the contract between the domain experts and the code. A class named with a word nobody defined is either a concept the experts do not know, or a synonym that will split the vocabulary in two. Writing the term and its meaning first forces the conversation that the name needs.',
+        bad: `// CONTEXT.md glossary: Invoice, Issue
+export class BillDispatcher {}`,
+        good: `// CONTEXT.md glossary: Invoice, Issue
+export class IssueInvoiceCommand {}`,
+    },
+    'language/no-technical-name': {
+        why: 'Manager, Helper, Data or Impl say how a class is built, not what it means. In the domain such a name marks a concept that was not discussed: the behaviour ends up in a bag that keeps growing. A domain expert never says "invoice manager".',
+        bad: `export class InvoiceManager {}`,
+        good: `export class InvoiceNumbering {}`,
+    },
+    'purity/no-system-clock': {
+        why: 'Code that reads the clock gives a different answer every time it runs, so its tests are either flaky or need a mocked module. Passing the instant in, from the Clock port, makes every rule about time testable with a fixed date and replayable in production.',
+        bad: `isOverdue(): boolean { return this.dueDate < new Date(); }`,
+        good: `isOverdue(now: Date): boolean { return this.dueDate < now; }`,
+    },
+    'purity/no-ambient-randomness': {
+        why: 'An identifier drawn inside the domain cannot be predicted by a test nor chosen by the caller (idempotent retries, imports of existing data). The IdGenerator port keeps the choice of the scheme in the composition root and gives tests readable, sequential identifiers.',
+        bad: `static create(): Invoice { return new Invoice(crypto.randomUUID()); }`,
+        good: `static create(id: string): Invoice { return new Invoice(id); }`,
+    },
+    'purity/no-environment': {
+        why: 'Reading the environment, logging to the console or touching the network from the domain or a handler hides a dependency that no constructor declares. The class then needs the real world, or a mocked module, to be tested. Every such access is a port with an adapter.',
+        bad: `if (process.env.FEATURE_X) console.log('issuing', invoice);`,
+        good: `constructor(private readonly features: FeatureFlags) {}`,
+    },
+};
+//# sourceMappingURL=language-docs.js.map

package/dist/check/explain/language-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-docs.js","sourceRoot":"","sources":["../../../src/check/explain/language-docs.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,aAAa,GAAsC;IAC9D,wBAAwB,EAAE;QACxB,GAAG,EAAE,gTAAgT;QACrT,GAAG,EAAE;+BACsB;QAC3B,IAAI,EAAE;oCAC0B;KACjC;IACD,4BAA4B,EAAE;QAC5B,GAAG,EAAE,+OAA+O;QACpP,GAAG,EAAE,gCAAgC;QACrC,IAAI,EAAE,kCAAkC;KACzC;IACD,wBAAwB,EAAE;QACxB,GAAG,EAAE,iQAAiQ;QACtQ,GAAG,EAAE,4DAA4D;QACjE,IAAI,EAAE,8DAA8D;KACrE;IACD,8BAA8B,EAAE;QAC9B,GAAG,EAAE,4QAA4Q;QACjR,GAAG,EAAE,uEAAuE;QAC5E,IAAI,EAAE,gEAAgE;KACvE;IACD,uBAAuB,EAAE;QACvB,GAAG,EAAE,2QAA2Q;QAChR,GAAG,EAAE,6DAA6D;QAClE,IAAI,EAAE,yDAAyD;KAChE;CACF,CAAC"}

package/dist/check/explain/layer-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from '../model/rule-doc.js';
+export declare const LAYER_DOCS: Readonly<Record<string, RuleDoc>>;
+//# sourceMappingURL=layer-docs.d.ts.map

package/dist/check/explain/layer-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer-docs.d.ts","sourceRoot":"","sources":["../../../src/check/explain/layer-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqCxD,CAAC"}

package/dist/check/explain/layer-docs.js

@@ -0,0 +1,39 @@
+export const LAYER_DOCS = {
+    'layer/domain-purity': {
+        why: 'The domain is the part of the system that has to survive a change of framework, database or transport. Every outside import ties a business rule to a technical choice and makes it impossible to test without that choice. Values that come from the outside world (ids, time, randomness) enter as parameters. The packages that apply a concern from outside (@ddd-ts-kit/aspects, audit, redis, scheduling, sentry, tracing) are refused whatever `domainAllowedPackages` says. The kernel itself is allowed, its entry @ddd-ts-kit/kernel/declarations is not: a declaration is wiring, and the domain declares nothing, neither a decorator on a class nor a dependency list. A repository port is a plain abstract class.',
+        bad: `// domain/aggregates/invoice.aggregate.ts
+import { randomUUID } from 'node:crypto';
+import { IsEmail } from 'class-validator';
+import { Logged } from '@ddd-ts-kit/aspects/decorators';
+import { Repository } from '@ddd-ts-kit/kernel/declarations';`,
+        good: `// domain/aggregates/invoice.aggregate.ts
+import { AggregateRoot } from '@ddd-ts-kit/kernel';
+import { Money } from '@/contexts/billing/domain/value-objects/money.vo.js';`,
+    },
+    'layer/application-inward': {
+        why: 'A use case orchestrates the domain and talks to the outside through ports. If it imports an adapter, a framework or a driver, the technical choice can no longer be replaced or faked, and the handler cannot be unit tested with plain fakes. Cross-cutting behaviour reaches a use case from outside: @ddd-ts-kit/aspects, audit, redis, scheduling, sentry and tracing are refused whatever `applicationAllowedPackages` says, their place is the composition root, a bus middleware or an adapter. The declarations of the kernel (@ddd-ts-kit/kernel/declarations) are part of the kernel and belong here: a handler, a job or a policy says what it is and names the ports it depends on, which are abstract classes, without knowing a container.',
+        bad: `// application/commands/issue-invoice/issue-invoice.handler.ts
+import { PgInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/pg-invoice.repository.js';
+import { RedisCache } from '@ddd-ts-kit/redis';
+import { retry } from '@ddd-ts-kit/aspects';`,
+        good: `// application/commands/issue-invoice/issue-invoice.handler.ts
+import { Cache, Clock } from '@ddd-ts-kit/kernel';
+import { CommandHandler } from '@ddd-ts-kit/kernel/declarations';
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';`,
+    },
+    'layer/presentation-no-infrastructure': {
+        why: 'A route translates a transport request into a command or a query and maps the answer back. Reaching an adapter directly skips the use case, so the business rule that guards the operation is skipped too.',
+        bad: `// presentation/http/issue-invoice.route.ts
+import { PgInvoiceRepository } from '@/contexts/billing/infrastructure/persistence/pg-invoice.repository.js';`,
+        good: `// presentation/http/issue-invoice.route.ts
+import type { IssueInvoiceHandler } from '@/contexts/billing/application/commands/issue-invoice/issue-invoice.handler.js';`,
+    },
+    'layer/infrastructure-no-presentation': {
+        why: 'Adapters implement ports declared inward. An adapter that knows a DTO or a route depends on one transport, and both outer layers start changing together.',
+        bad: `// infrastructure/persistence/pg-invoice.repository.ts
+import type { InvoiceDto } from '@/contexts/billing/presentation/http/invoice.dto.js';`,
+        good: `// infrastructure/persistence/pg-invoice.repository.ts
+import { InvoiceRepository } from '@/contexts/billing/domain/repositories/invoice.repository.js';`,
+    },
+};
+//# sourceMappingURL=layer-docs.js.map

package/dist/check/explain/layer-docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer-docs.js","sourceRoot":"","sources":["../../../src/check/explain/layer-docs.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,UAAU,GAAsC;IAC3D,qBAAqB,EAAE;QACrB,GAAG,EAAE,ksBAAksB;QACvsB,GAAG,EAAE;;;;8DAIqD;QAC1D,IAAI,EAAE;;6EAEmE;KAC1E;IACD,0BAA0B,EAAE;QAC1B,GAAG,EAAE,0tBAA0tB;QAC/tB,GAAG,EAAE;;;6CAGoC;QACzC,IAAI,EAAE;;;kGAGwF;KAC/F;IACD,sCAAsC,EAAE;QACtC,GAAG,EAAE,4MAA4M;QACjN,GAAG,EAAE;8GACqG;QAC1G,IAAI,EAAE;2HACiH;KACxH;IACD,sCAAsC,EAAE;QACtC,GAAG,EAAE,2JAA2J;QAChK,GAAG,EAAE;uFAC8E;QACnF,IAAI,EAAE;kGACwF;KAC/F;CACF,CAAC"}

package/dist/check/explain/layout-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from '../model/rule-doc.js';
+export declare const LAYOUT_DOCS: Readonly<Record<string, RuleDoc>>;
+//# sourceMappingURL=layout-docs.d.ts.map

package/dist/check/explain/layout-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-docs.d.ts","sourceRoot":"","sources":["../../../src/check/explain/layout-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuEzD,CAAC"}