@living-architecture/riviere-extract-conventions-published-language 0.7.0

package/src/published-language/default-extraction.config.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://living-architecture.dev/schemas/extraction-config.schema.json",
+  "modules": [
+    {
+      "name": "default",
+      "domain": "default",
+      "path": ".",
+      "glob": "**/*.ts",
+      "api": {
+        "find": "methods",
+        "where": {
+          "inClassWith": {
+            "hasDecorator": {
+              "name": "APIContainer",
+              "from": "@living-architecture/riviere-extract-conventions-published-language"
+            }
+          }
+        },
+        "extract": {
+          "apiType": { "literal": "REST" },
+          "route": { "fromProperty": { "name": "route", "kind": "instance" } },
+          "method": { "fromProperty": { "name": "method", "kind": "instance" } }
+        }
+      },
+      "useCase": {
+        "find": "classes",
+        "where": {
+          "hasDecorator": {
+            "name": "UseCase",
+            "from": "@living-architecture/riviere-extract-conventions-published-language"
+          }
+        }
+      },
+      "domainOp": {
+        "find": "methods",
+        "where": {
+          "inClassWith": {
+            "hasDecorator": {
+              "name": "DomainOpContainer",
+              "from": "@living-architecture/riviere-extract-conventions-published-language"
+            }
+          }
+        },
+        "extract": {
+          "operationName": { "fromMethodName": true }
+        }
+      },
+      "event": {
+        "find": "classes",
+        "where": {
+          "hasDecorator": {
+            "name": "Event",
+            "from": "@living-architecture/riviere-extract-conventions-published-language"
+          }
+        },
+        "extract": {
+          "eventName": { "fromClassName": true }
+        }
+      },
+      "eventHandler": {
+        "find": "methods",
+        "where": {
+          "inClassWith": {
+            "hasDecorator": {
+              "name": "EventHandlerContainer",
+              "from": "@living-architecture/riviere-extract-conventions-published-language"
+            }
+          }
+        },
+        "extract": {
+          "subscribedEvents": { "fromProperty": { "name": "subscribedEvents", "kind": "instance" } }
+        }
+      },
+      "ui": {
+        "find": "classes",
+        "where": {
+          "hasDecorator": {
+            "name": "UI",
+            "from": "@living-architecture/riviere-extract-conventions-published-language"
+          }
+        },
+        "extract": {
+          "route": { "fromProperty": { "name": "route", "kind": "static" } }
+        }
+      },
+      "customTypes": {
+        "eventPublisher": {
+          "find": "methods",
+          "where": {
+            "inClassWith": {
+              "hasDecorator": {
+                "name": "EventPublisherContainer",
+                "from": "@living-architecture/riviere-extract-conventions-published-language"
+              }
+            }
+          },
+          "extract": {
+            "publishedEventType": { "fromParameterType": { "position": 0 } }
+          }
+        },
+        "httpCall": {
+          "find": "methods",
+          "where": {
+            "and": [
+              {
+                "hasDecorator": {
+                  "name": "HttpCall",
+                  "from": "@living-architecture/riviere-extract-conventions-published-language"
+                }
+              },
+              {
+                "inClassWith": {
+                  "hasDecorator": {
+                    "name": "HttpClient",
+                    "from": "@living-architecture/riviere-extract-conventions-published-language"
+                  }
+                }
+              }
+            ]
+          },
+          "extract": {
+            "serviceName": {
+              "fromClassDecoratorArg": {
+                "decorator": "HttpClient",
+                "position": 0
+              }
+            },
+            "route": {
+              "fromDecoratorArg": {
+                "decorator": "HttpCall",
+                "position": 0
+              }
+            },
+            "method": {
+              "fromDecoratorArg": {
+                "decorator": "HttpCall",
+                "position": 1
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "connections": {
+    "eventPublishers": [
+      {
+        "fromType": "eventPublisher",
+        "metadataKey": "publishedEventType"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,85 @@
+const {
+  hasDecorator,
+  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 @APIContainer classes to have route and method with literal values' },
+    schema: [],
+    messages: {
+      missingRoute: "Class '{{className}}' decorated with @APIContainer but is missing 'route' property",
+      missingMethod: "Class '{{className}}' decorated with @APIContainer 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 (!hasDecorator(node, 'APIContainer')) 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/published-language/eslint-plugin/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/published-language/eslint-plugin/event-handler-requires-subscribed-events.cjs

@@ -0,0 +1,47 @@
+const {
+  hasDecorator,
+  findInstanceProperty,
+  hasStringLiteralArrayValue,
+  getValueTypeDescription,
+} = require('./interface-ast-predicates.cjs')
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Require @EventHandlerContainer classes to have subscribedEvents array with literal values' },
+    schema: [],
+    messages: {
+      missingSubscribedEvents: "Class '{{className}}' has @EventHandlerContainer 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 -- ESLint ClassDeclaration visitor guarantees node.id exists per estree spec; structurally unreachable */
+        if (!node.id) return
+        if (!hasDecorator(node, 'EventHandlerContainer')) return
+
+        const className = node.id.name
+        const subscribedEventsProperty = findInstanceProperty(node, 'subscribedEvents')
+
+        if (!subscribedEventsProperty) {
+          context.report({
+            node: node.id,
+            messageId: 'missingSubscribedEvents',
+            data: { className },
+          })
+        } else if (!hasStringLiteralArrayValue(subscribedEventsProperty)) {
+          context.report({
+            node: subscribedEventsProperty,
+            messageId: 'subscribedEventsNotLiteralArray',
+            data: {
+              className,
+              actualType: getValueTypeDescription(subscribedEventsProperty),
+            },
+          })
+        }
+      },
+    }
+  },
+}

package/src/published-language/eslint-plugin/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/published-language/eslint-plugin/event-publisher-method-signature.cjs

@@ -0,0 +1,179 @@
+const { hasDecorator } = require('./interface-ast-predicates.cjs')
+
+let getParserServices = null
+try {
+  getParserServices = require('@typescript-eslint/utils').ESLintUtils.getParserServices
+/* v8 ignore next -- soft-require: package always present in this repo */
+} catch { /* type checking unavailable */ }
+
+function getTypeReferenceName(typeAnnotation) {
+  const typeName = typeAnnotation.typeName
+  if (typeName.type === 'TSQualifiedName') {
+    return typeName.right.name
+  }
+  return typeName.name
+}
+
+function checkEventTypeShape(checker, services, param, typeAnnotation) {
+  if (!checker || !services) return null
+
+  const tsParam = services.esTreeNodeToTSNodeMap.get(param)
+  const paramType = checker.getTypeAtLocation(tsParam)
+  const typeProperty = paramType.getProperty('type')
+  const referenceName = getTypeReferenceName(typeAnnotation)
+
+  if (!typeProperty) {
+    return referenceName
+  }
+
+  const typePropertyType = checker.getTypeOfSymbol(typeProperty)
+  const stringType = checker.getStringType()
+  if (!checker.isTypeAssignableTo(typePropertyType, stringType)) {
+    return referenceName
+  }
+
+  return null
+}
+
+function checkMethod(context, member, className, checker, services) {
+  const methodName = member.key.name
+
+  if (member.accessibility === 'private' || member.accessibility === 'protected') {
+    context.report({
+      node: member.key,
+      messageId: 'nonPublicMethod',
+      data: {
+        methodName,
+        className,
+        accessibility: member.accessibility,
+      },
+    })
+    return
+  }
+
+  const params = member.value.params
+
+  if (params.length === 0) {
+    context.report({
+      node: member.key,
+      messageId: 'missingParameter',
+      data: {
+        methodName,
+        className,
+      },
+    })
+    return
+  }
+
+  if (params.length > 1) {
+    context.report({
+      node: member.key,
+      messageId: 'tooManyParameters',
+      data: {
+        methodName,
+        className,
+      },
+    })
+    return
+  }
+
+  const param = params[0]
+  const typeAnnotation = param.typeAnnotation && param.typeAnnotation.typeAnnotation
+
+  if (!typeAnnotation) {
+    context.report({
+      node: member.key,
+      messageId: 'missingTypeAnnotation',
+      data: {
+        methodName,
+        className,
+      },
+    })
+    return
+  }
+
+  if (typeAnnotation.type !== 'TSTypeReference') {
+    context.report({
+      node: member.key,
+      messageId: 'notTypeReference',
+      data: {
+        methodName,
+        className,
+      },
+    })
+    return
+  }
+
+  const failedTypeName = checkEventTypeShape(checker, services, param, typeAnnotation)
+  if (failedTypeName) {
+    context.report({
+      node: member.key,
+      messageId: 'invalidEventType',
+      data: {
+        typeName: failedTypeName,
+        methodName,
+        className,
+      },
+    })
+  }
+}
+
+function isMethodToCheck(member) {
+  return (
+    member.type === 'MethodDefinition' &&
+    member.kind !== 'constructor' &&
+    member.kind !== 'get' &&
+    member.kind !== 'set'
+  )
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require @EventPublisherContainer methods to have exactly one typed event parameter',
+      requiresTypeChecking: true,
+      examples: {
+        valid: "@EventPublisherContainer class OrderPublisher { publish(event: OrderPlacedEvent): void {} }",
+        invalid: "@EventPublisherContainer class OrderPublisher { publish(): void {} }",
+      },
+    },
+    schema: [],
+    messages: {
+      missingParameter: "Method '{{methodName}}' on @EventPublisherContainer class '{{className}}' must have exactly one parameter",
+      tooManyParameters: "Method '{{methodName}}' on @EventPublisherContainer class '{{className}}' must have exactly one parameter",
+      missingTypeAnnotation: "Parameter of method '{{methodName}}' on @EventPublisherContainer class '{{className}}' must have a type annotation",
+      notTypeReference: "Parameter of method '{{methodName}}' on @EventPublisherContainer class '{{className}}' must have a type reference annotation",
+      invalidEventType: "Parameter type '{{typeName}}' of method '{{methodName}}' on @EventPublisherContainer class '{{className}}' must have a 'type: string' property",
+      nonPublicMethod: "Method '{{methodName}}' on @EventPublisherContainer class '{{className}}' must be public, but is {{accessibility}}",
+    },
+  },
+  create(context) {
+    let services = null
+    let checker = null
+    /* v8 ignore start -- graceful degradation: getParserServices always available in this repo */
+    if (getParserServices) {
+      try {
+        services = getParserServices(context, true)
+        checker = services.program?.getTypeChecker() ?? null
+      } catch { /* no type info */ }
+    }
+    /* v8 ignore stop */
+
+    return {
+      ClassDeclaration(node) {
+        /* v8 ignore next -- ClassDeclaration always has id (name) */
+        if (!node.id) return
+        if (!hasDecorator(node, 'EventPublisherContainer')) return
+
+        const className = node.id.name
+
+        for (const member of node.body.body) {
+          if (isMethodToCheck(member)) {
+            checkMethod(context, member, className, checker, services)
+          }
+        }
+      },
+    }
+  },
+}

package/src/published-language/eslint-plugin/event-publisher-method-signature.d.cts

@@ -0,0 +1,6 @@
+import type { TSESLint } from '@typescript-eslint/utils'
+
+type MessageIds = 'missingParameter' | 'tooManyParameters' | 'missingTypeAnnotation' | 'notTypeReference' | 'invalidEventType' | 'nonPublicMethod'
+
+declare const rule: TSESLint.RuleModule<MessageIds>
+export default rule

package/src/published-language/eslint-plugin/event-requires-type-property.cjs

@@ -0,0 +1,47 @@
+const {
+  hasDecorator,
+  findInstanceProperty,
+  hasStringLiteralValue,
+  getValueTypeDescription,
+} = require('./interface-ast-predicates.cjs')
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Require @Event classes to have type property with literal value' },
+    schema: [],
+    messages: {
+      missingType: "Class '{{className}}' decorated with @Event 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 (!hasDecorator(node, 'Event')) 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/published-language/eslint-plugin/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/published-language/eslint-plugin/http-call-requires-http-client-container.cjs

@@ -0,0 +1,68 @@
+function hasDecoratorNamed(decorators, decoratorName) {
+  /* v8 ignore next 3 -- typescript-eslint provides an array for decorators on class and method nodes; undefined is structurally unreachable in current parser output */
+  if (!decorators) {
+    return false
+  }
+  return decorators.some((decorator) => {
+    const expression = decorator.expression
+    if (expression.type === 'Identifier') {
+      return expression.name === decoratorName
+    }
+    return (
+      expression.type === 'CallExpression' &&
+      expression.callee.type === 'Identifier' &&
+      expression.callee.name === decoratorName
+    )
+  })
+}
+
+function isMethodWithHttpCallDecorator(member) {
+  if (member.type !== 'MethodDefinition') {
+    return false
+  }
+  if (member.key.type !== 'Identifier') {
+    return false
+  }
+  return hasDecoratorNamed(member.decorators, 'HttpCall')
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Require HttpCall methods to be inside HttpClient classes' },
+    schema: [],
+    messages: {
+      missingHttpClientContainer:
+        "Method '{{methodName}}' uses @HttpCall but its class '{{className}}' is missing @HttpClient",
+    },
+  },
+  create(context) {
+    return {
+      ClassDeclaration(node) {
+        if (!node.id) {
+          return
+        }
+
+        const hasHttpClientDecorator = hasDecoratorNamed(node.decorators, 'HttpClient')
+        if (hasHttpClientDecorator) {
+          return
+        }
+
+        for (const member of node.body.body) {
+          if (!isMethodWithHttpCallDecorator(member)) {
+            continue
+          }
+
+          context.report({
+            node: member.key,
+            messageId: 'missingHttpClientContainer',
+            data: {
+              className: node.id.name,
+              methodName: member.key.name,
+            },
+          })
+        }
+      },
+    }
+  },
+}

package/src/published-language/eslint-plugin/http-call-requires-http-client-container.d.cts

@@ -0,0 +1,5 @@
+import type { TSESLint } from '@typescript-eslint/utils'
+
+declare const rule: TSESLint.RuleModule<string, readonly unknown[]>
+
+export = rule