@living-architecture/riviere-extract-conventions 0.3.24 → 0.3.26

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { DomainOpContainer, APIContainer, EventHandlerContainer, UseCase, Event, UI, DomainOp, APIEndpoint, EventHandler, Custom, Ignore, getCustomType, } from './decorators';
+export type { HttpMethod, APIControllerDef, EventDef, EventHandlerDef, UIPageDef, DomainOpContainerDef, } from './interfaces';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EAErB,OAAO,EACP,KAAK,EACL,EAAE,EAEF,QAAQ,EACR,WAAW,EACX,YAAY,EAEZ,MAAM,EACN,MAAM,EAEN,aAAa,GACd,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EACjB,YAAY,EACZ,qBAAqB,EAErB,OAAO,EACP,KAAK,EACL,EAAE,EAEF,QAAQ,EACR,WAAW,EACX,YAAY,EAEZ,MAAM,EACN,MAAM,EAEN,aAAa,GACd,MAAM,cAAc,CAAA;AAGrB,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,SAAS,EACT,oBAAoB,GACrB,MAAM,cAAc,CAAA"}

package/dist/interfaces.d.ts

@@ -0,0 +1,59 @@
+/**
+ * HTTP methods supported for API controllers.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Interface for API controller classes.
+ * Classes implementing this interface represent HTTP endpoint handlers.
+ *
+ * Required properties:
+ * - route: The URL path for this endpoint
+ * - method: The HTTP method (GET, POST, PUT, PATCH, DELETE)
+ * - handle: The request handler function
+ */
+export interface APIControllerDef {
+    readonly route: string;
+    readonly method: HttpMethod;
+    handle(req: Request, res: Response): void | Promise<void>;
+}
+/**
+ * Interface for domain event classes.
+ * Classes implementing this interface represent events that have occurred in the domain.
+ *
+ * Required properties:
+ * - type: A unique identifier for this event type (should be a string literal)
+ */
+export interface EventDef {
+    readonly type: string;
+}
+/**
+ * Interface for event handler classes.
+ * Classes implementing this interface subscribe to and process domain events.
+ *
+ * Required properties:
+ * - subscribedEvents: Array of event type names this handler processes
+ * - handle: The event processing function
+ */
+export interface EventHandlerDef {
+    readonly subscribedEvents: readonly string[];
+    handle(event: unknown): void | Promise<void>;
+}
+/**
+ * Interface for UI page classes.
+ * Classes implementing this interface represent routable UI pages.
+ *
+ * Required properties:
+ * - route: The URL path for this page
+ */
+export interface UIPageDef {
+    readonly route: string;
+}
+/**
+ * Marker interface for domain operation container classes.
+ * Classes implementing this interface contain domain operations as methods.
+ * No required properties - the class itself serves as the container.
+ */
+export interface DomainOpContainerDef {
+    readonly __brand?: 'DomainOpContainerDef';
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAA;CAAC"}

package/dist/interfaces.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@living-architecture/riviere-extract-conventions",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -32,6 +32,6 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@living-architecture/riviere-extract-config": "0.3.3"
+    "@living-architecture/riviere-extract-config": "0.3.5"
   }
 }

package/src/default-extraction.config.json

@@ -13,6 +13,9 @@
               "from": "@living-architecture/riviere-extract-conventions"
             }
           }
+        },
+        "extract": {
+          "apiType": { "literal": "REST" }
         }
       },
       "useCase": {
@@ -33,6 +36,9 @@
               "from": "@living-architecture/riviere-extract-conventions"
             }
           }
+        },
+        "extract": {
+          "operationName": { "fromMethodName": true }
         }
       },
       "event": {
@@ -42,6 +48,9 @@
             "name": "Event",
             "from": "@living-architecture/riviere-extract-conventions"
           }
+        },
+        "extract": {
+          "eventName": { "fromClassName": true }
         }
       },
       "eventHandler": {
@@ -53,6 +62,9 @@
               "from": "@living-architecture/riviere-extract-conventions"
             }
           }
+        },
+        "extract": {
+          "subscribedEvents": { "fromGenericArg": { "interface": "IEventHandler", "position": 0 } }
         }
       },
       "ui": {
@@ -62,6 +74,9 @@
             "name": "UI",
             "from": "@living-architecture/riviere-extract-conventions"
           }
+        },
+        "extract": {
+          "route": { "fromProperty": { "name": "route", "kind": "static" } }
         }
       }
     }

package/src/eslint/api-controller-requires-route-and-method.cjs

@@ -0,0 +1,85 @@
+const {
+  implementsInterface,
+  findInstanceProperty,
+  hasStringLiteralValue,
+  getLiteralValue,
+  getValueTypeDescription,
+} = require('./interface-ast-predicates.cjs')
+
+const VALID_HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Require APIControllerDef implementations to have route and method with literal values' },
+    schema: [],
+    messages: {
+      missingRoute: "Class '{{className}}' implements APIControllerDef but is missing 'route' property",
+      missingMethod: "Class '{{className}}' implements APIControllerDef but is missing 'method' property",
+      routeNotLiteral: "Class '{{className}}' has 'route' property but value must be a string literal, not {{actualType}}",
+      methodNotLiteral: "Class '{{className}}' has 'method' property but value must be a string literal, not {{actualType}}",
+      invalidHttpMethod: "Class '{{className}}' has invalid HTTP method '{{value}}'. Must be one of: GET, POST, PUT, PATCH, DELETE",
+    },
+  },
+  create(context) {
+    return {
+      ClassDeclaration(node) {
+        /* v8 ignore next -- ClassDeclaration always has id (name) */
+        if (!node.id) return
+        if (!implementsInterface(node, 'APIControllerDef')) return
+
+        const className = node.id.name
+        const routeProperty = findInstanceProperty(node, 'route')
+        const methodProperty = findInstanceProperty(node, 'method')
+
+        // Check route property
+        if (!routeProperty) {
+          context.report({
+            node: node.id,
+            messageId: 'missingRoute',
+            data: { className },
+          })
+        } else if (!hasStringLiteralValue(routeProperty)) {
+          context.report({
+            node: routeProperty,
+            messageId: 'routeNotLiteral',
+            data: {
+              className,
+              actualType: getValueTypeDescription(routeProperty),
+            },
+          })
+        }
+
+        // Check method property
+        if (!methodProperty) {
+          context.report({
+            node: node.id,
+            messageId: 'missingMethod',
+            data: { className },
+          })
+        } else if (!hasStringLiteralValue(methodProperty)) {
+          context.report({
+            node: methodProperty,
+            messageId: 'methodNotLiteral',
+            data: {
+              className,
+              actualType: getValueTypeDescription(methodProperty),
+            },
+          })
+        } else {
+          const methodValue = getLiteralValue(methodProperty)
+          if (!VALID_HTTP_METHODS.includes(methodValue)) {
+            context.report({
+              node: methodProperty,
+              messageId: 'invalidHttpMethod',
+              data: {
+                className,
+                value: methodValue,
+              },
+            })
+          }
+        }
+      },
+    }
+  },
+}

package/src/eslint/api-controller-requires-route-and-method.d.cts

@@ -0,0 +1,6 @@
+import type { TSESLint } from '@typescript-eslint/utils'
+
+type MessageIds = 'missingRoute' | 'missingMethod' | 'routeNotLiteral' | 'methodNotLiteral' | 'invalidHttpMethod'
+
+declare const rule: TSESLint.RuleModule<MessageIds>
+export default rule

package/src/eslint/event-handler-requires-subscribed-events.cjs

@@ -0,0 +1,47 @@
+const {
+  implementsInterface,
+  findInstanceProperty,
+  hasLiteralArrayValue,
+  getValueTypeDescription,
+} = require('./interface-ast-predicates.cjs')
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Require EventHandlerDef implementations to have subscribedEvents array with literal values' },
+    schema: [],
+    messages: {
+      missingSubscribedEvents: "Class '{{className}}' implements EventHandlerDef but is missing 'subscribedEvents' property",
+      subscribedEventsNotLiteralArray: "Class '{{className}}' has 'subscribedEvents' property but value must be an array of string literals, not {{actualType}}",
+    },
+  },
+  create(context) {
+    return {
+      ClassDeclaration(node) {
+        /* v8 ignore next -- ClassDeclaration always has id (name) */
+        if (!node.id) return
+        if (!implementsInterface(node, 'EventHandlerDef')) return
+
+        const className = node.id.name
+        const subscribedEventsProperty = findInstanceProperty(node, 'subscribedEvents')
+
+        if (!subscribedEventsProperty) {
+          context.report({
+            node: node.id,
+            messageId: 'missingSubscribedEvents',
+            data: { className },
+          })
+        } else if (!hasLiteralArrayValue(subscribedEventsProperty)) {
+          context.report({
+            node: subscribedEventsProperty,
+            messageId: 'subscribedEventsNotLiteralArray',
+            data: {
+              className,
+              actualType: getValueTypeDescription(subscribedEventsProperty),
+            },
+          })
+        }
+      },
+    }
+  },
+}

package/src/eslint/event-handler-requires-subscribed-events.d.cts

@@ -0,0 +1,6 @@
+import type { TSESLint } from '@typescript-eslint/utils'
+
+type MessageIds = 'missingSubscribedEvents' | 'subscribedEventsNotLiteralArray'
+
+declare const rule: TSESLint.RuleModule<MessageIds>
+export default rule

package/src/eslint/event-requires-type-property.cjs

@@ -0,0 +1,47 @@
+const {
+  implementsInterface,
+  findInstanceProperty,
+  hasStringLiteralValue,
+  getValueTypeDescription,
+} = require('./interface-ast-predicates.cjs')
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Require EventDef implementations to have type property with literal value' },
+    schema: [],
+    messages: {
+      missingType: "Class '{{className}}' implements EventDef but is missing 'type' property",
+      typeNotLiteral: "Class '{{className}}' has 'type' property but value must be a string literal, not {{actualType}}",
+    },
+  },
+  create(context) {
+    return {
+      ClassDeclaration(node) {
+        /* v8 ignore next -- ClassDeclaration always has id (name) */
+        if (!node.id) return
+        if (!implementsInterface(node, 'EventDef')) return
+
+        const className = node.id.name
+        const typeProperty = findInstanceProperty(node, 'type')
+
+        if (!typeProperty) {
+          context.report({
+            node: node.id,
+            messageId: 'missingType',
+            data: { className },
+          })
+        } else if (!hasStringLiteralValue(typeProperty)) {
+          context.report({
+            node: typeProperty,
+            messageId: 'typeNotLiteral',
+            data: {
+              className,
+              actualType: getValueTypeDescription(typeProperty),
+            },
+          })
+        }
+      },
+    }
+  },
+}

package/src/eslint/event-requires-type-property.d.cts

@@ -0,0 +1,6 @@
+import type { TSESLint } from '@typescript-eslint/utils'
+
+type MessageIds = 'missingType' | 'typeNotLiteral'
+
+declare const rule: TSESLint.RuleModule<MessageIds>
+export default rule

package/src/eslint/index.cjs

@@ -1,3 +1,15 @@
 const requireComponentDecorator = require('./require-component-decorator.cjs')
+const apiControllerRequiresRouteAndMethod = require('./api-controller-requires-route-and-method.cjs')
+const eventRequiresTypeProperty = require('./event-requires-type-property.cjs')
+const eventHandlerRequiresSubscribedEvents = require('./event-handler-requires-subscribed-events.cjs')
+const uiPageRequiresRoute = require('./ui-page-requires-route.cjs')
 
-module.exports = { rules: { 'require-component-decorator': requireComponentDecorator } }
+module.exports = {
+  rules: {
+    'require-component-decorator': requireComponentDecorator,
+    'api-controller-requires-route-and-method': apiControllerRequiresRouteAndMethod,
+    'event-requires-type-property': eventRequiresTypeProperty,
+    'event-handler-requires-subscribed-events': eventHandlerRequiresSubscribedEvents,
+    'ui-page-requires-route': uiPageRequiresRoute,
+  },
+}

package/src/eslint/index.d.ts

@@ -3,6 +3,18 @@ import type { TSESLint } from '@typescript-eslint/utils'
 interface Plugin {
   rules: {
     'require-component-decorator': TSESLint.RuleModule<'missingDecorator'>
+    'api-controller-requires-route-and-method': TSESLint.RuleModule<
+      | 'missingRoute'
+      | 'missingMethod'
+      | 'routeNotLiteral'
+      | 'methodNotLiteral'
+      | 'invalidHttpMethod'
+    >
+    'event-requires-type-property': TSESLint.RuleModule<'missingType' | 'typeNotLiteral'>
+    'event-handler-requires-subscribed-events': TSESLint.RuleModule<
+      'missingSubscribedEvents' | 'subscribedEventsNotLiteralArray'
+    >
+    'ui-page-requires-route': TSESLint.RuleModule<'missingRoute' | 'routeNotLiteral'>
   }
 }
 

package/src/eslint/interface-ast-predicates.cjs

@@ -0,0 +1,143 @@
+/**
+ * Shared utilities for ESLint rules that check interface implementations.
+ */
+
+/**
+ * Checks if a class implements a specific interface by name.
+ * @param {object} node - ClassDeclaration AST node
+ * @param {string} interfaceName - Name of interface to check
+ * @returns {boolean} True if class implements the interface
+ */
+function implementsInterface(node, interfaceName) {
+  if (!node.implements || node.implements.length === 0) {
+    return false
+  }
+  return node.implements.some((impl) => {
+    // Handle simple identifier: implements APIControllerDef
+    if (impl.expression && impl.expression.type === 'Identifier') {
+      return impl.expression.name === interfaceName
+    }
+    // Handle qualified name: implements SomeModule.APIControllerDef
+    /* v8 ignore next 4 -- defensive check: implements array always has expression */
+    if (impl.expression && impl.expression.type === 'TSQualifiedName') {
+      return impl.expression.right.name === interfaceName
+    }
+    return false
+  })
+}
+
+/**
+ * Finds an instance property (non-static) by name in class body.
+ * @param {object} classNode - ClassDeclaration AST node
+ * @param {string} propertyName - Name of property to find
+ * @returns {object|null} PropertyDefinition node or null
+ */
+function findInstanceProperty(classNode, propertyName) {
+  /* v8 ignore next 3 -- defensive check: ClassDeclaration always has body in practice */
+  if (!classNode.body || !classNode.body.body) {
+    return null
+  }
+  return classNode.body.body.find((member) => {
+    return (
+      member.type === 'PropertyDefinition' &&
+      member.static !== true &&
+      member.key &&
+      member.key.type === 'Identifier' &&
+      member.key.name === propertyName
+    )
+  }) || null
+}
+
+/**
+ * Checks if a property has a literal value (string, number, boolean).
+ * @param {object} property - PropertyDefinition AST node
+ * @returns {boolean} True if value is a literal
+ */
+/* v8 ignore start -- exported utility for consumers, not used internally */
+function hasLiteralValue(property) {
+  if (!property || !property.value) {
+    return false
+  }
+  return property.value.type === 'Literal'
+}
+/* v8 ignore stop */
+
+/**
+ * Checks if a property has a string literal value specifically.
+ * @param {object} property - PropertyDefinition AST node
+ * @returns {boolean} True if value is a string literal
+ */
+function hasStringLiteralValue(property) {
+  /* v8 ignore next 3 -- defensive check: rules always check property existence first */
+  if (!property || !property.value) {
+    return false
+  }
+  return property.value.type === 'Literal' && typeof property.value.value === 'string'
+}
+
+/**
+ * Checks if a property has an array literal value with only literal elements.
+ * @param {object} property - PropertyDefinition AST node
+ * @returns {boolean} True if value is an array of literals
+ */
+function hasLiteralArrayValue(property) {
+  /* v8 ignore next 3 -- defensive check: rules always check property existence first */
+  if (!property || !property.value) {
+    return false
+  }
+  if (property.value.type !== 'ArrayExpression') {
+    return false
+  }
+  return property.value.elements.every(
+    (element) => element && element.type === 'Literal'
+  )
+}
+
+/**
+ * Gets the literal value from a property, or null if not a literal.
+ * @param {object} property - PropertyDefinition AST node
+ * @returns {*} The literal value or null
+ */
+function getLiteralValue(property) {
+  /* v8 ignore next 3 -- defensive check: rules always check property existence first */
+  if (!property || !property.value || property.value.type !== 'Literal') {
+    return null
+  }
+  return property.value.value
+}
+
+/**
+ * Gets a human-readable type description for error messages.
+ * @param {object} property - PropertyDefinition AST node
+ * @returns {string} Type description
+ */
+function getValueTypeDescription(property) {
+  /* v8 ignore next 3 -- defensive check: only called when property exists */
+  if (!property || !property.value) {
+    return 'undefined'
+  }
+  const valueType = property.value.type
+  if (valueType === 'Identifier') {
+    return `variable reference '${property.value.name}'`
+  }
+  if (valueType === 'MemberExpression') {
+    return 'member expression (possibly an enum)'
+  }
+  if (valueType === 'CallExpression') {
+    return 'function call'
+  }
+  if (valueType === 'TemplateLiteral') {
+    return 'template literal'
+  }
+  return valueType
+}
+
+module.exports = {
+  implementsInterface,
+  findInstanceProperty,
+  hasLiteralValue,
+  hasStringLiteralValue,
+  hasLiteralArrayValue,
+  getLiteralValue,
+  getValueTypeDescription,
+}

package/src/eslint/ui-page-requires-route.cjs

@@ -0,0 +1,47 @@
+const {
+  implementsInterface,
+  findInstanceProperty,
+  hasStringLiteralValue,
+  getValueTypeDescription,
+} = require('./interface-ast-predicates.cjs')
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Require UIPageDef implementations to have route property with literal value' },
+    schema: [],
+    messages: {
+      missingRoute: "Class '{{className}}' implements UIPageDef but is missing 'route' property",
+      routeNotLiteral: "Class '{{className}}' has 'route' property but value must be a string literal, not {{actualType}}",
+    },
+  },
+  create(context) {
+    return {
+      ClassDeclaration(node) {
+        /* v8 ignore next -- ClassDeclaration always has id (name) */
+        if (!node.id) return
+        if (!implementsInterface(node, 'UIPageDef')) return
+
+        const className = node.id.name
+        const routeProperty = findInstanceProperty(node, 'route')
+
+        if (!routeProperty) {
+          context.report({
+            node: node.id,
+            messageId: 'missingRoute',
+            data: { className },
+          })
+        } else if (!hasStringLiteralValue(routeProperty)) {
+          context.report({
+            node: routeProperty,
+            messageId: 'routeNotLiteral',
+            data: {
+              className,
+              actualType: getValueTypeDescription(routeProperty),
+            },
+          })
+        }
+      },
+    }
+  },
+}

package/src/eslint/ui-page-requires-route.d.cts

@@ -0,0 +1,6 @@
+import type { TSESLint } from '@typescript-eslint/utils'
+
+type MessageIds = 'missingRoute' | 'routeNotLiteral'
+
+declare const rule: TSESLint.RuleModule<MessageIds>
+export default rule