@znight/http 0.1.2 → 0.1.4

package/src/compiler/route-decorators.ts

@@ -6,6 +6,10 @@
  * (the options) are statically evaluable. Its argument is evaluated like a `value` decorator
  * argument (literals, `const` references, references to exported bindings); without argument the
  * value is `true`. Decorators of one group are alternatives: one per controller or route.
+ *
+ * Every helper takes the analysis context of **any** extension: other extensions read route
+ * decorators on their own targets (gateways, resolvers) with {@link readRouteMeta}, exported by
+ * `@znight/http/compiler`.
  */
 import type {
   AnalyzeContext,
@@ -13,15 +17,16 @@ import type {
   DecoratorInfo,
   Diagnostic,
   Location,
+  MethodInfo,
   StaticValue,
   ValueRef,
 } from '@znight/compiler'
-import type { HttpControllerData, MetaEntry } from './model.ts'
+import type { MetaEntry } from './model.ts'
 
 import { type AstNode, child, children, isNode, unwrap } from './ast.ts'
 import { Codes, GROUP_NAME, Ids } from './model.ts'
 
-type Context = AnalyzeContext<HttpControllerData>
+type Context = AnalyzeContext<unknown>
 type Project = Context['project']
 type ScopeInput = Parameters<Project['evaluate']>[0]
 type ExpressionInput = Parameters<Project['evaluate']>[1]
@@ -295,6 +300,44 @@ export function routeMeta(
   return entries
 }
 
+/**
+ * The route metadata entries of a class (`method` omitted) or of one of its methods: the route
+ * decorators (`createRouteDecorator` consts) applied to that target, in source order, read exactly
+ * as the http extension reads controllers and routes (keys, statically evaluated values, groups,
+ * `required`). Problems are reported as ZNIGHT005 through `ctx`, once per call: read each target
+ * once. Decorators that are not route decorators are ignored.
+ *
+ * Works with the analysis context of any extension. The entries of a target are its own: combine a
+ * class and a method with {@link effectiveRouteMeta}.
+ *
+ * ```ts
+ * analyzeClass(cls, ctx) {
+ *   const classMeta = readRouteMeta(ctx, cls)
+ *   for (const method of cls.methods) {
+ *     const meta = effectiveRouteMeta(classMeta, readRouteMeta(ctx, cls, method))
+ *   }
+ * }
+ * ```
+ */
+export function readRouteMeta(ctx: AnalyzeContext<unknown>, cls: ClassInfo, method?: MethodInfo): MetaEntry[] {
+  return method === undefined
+    ? routeMeta(ctx, cls, cls.decorators, cls.displayName)
+    : routeMeta(ctx, cls, method.decorators, `${cls.displayName}.${method.name}`)
+}
+
+/**
+ * The effective metadata of a method from the entries of its class and its own (RFC 0001 §5.1):
+ * the class entries, except those of a group the method decides itself, then the method entries.
+ * The same rule as `ctx.route.meta` at runtime.
+ */
+export function effectiveRouteMeta(classMeta: readonly MetaEntry[], methodMeta: readonly MetaEntry[]): MetaEntry[] {
+  if (methodMeta.length === 0) {
+    return [...classMeta]
+  }
+  const decided = new Set(methodMeta.map(entry => entry.group))
+  return [...classMeta.filter(entry => !decided.has(entry.group)), ...methodMeta]
+}
+
 /** `true` when the decorator is a route metadata decorator. */
 export function isRouteMetaDecorator(ctx: Context, decorator: DecoratorInfo): boolean {
   return (

package/src/compiler/route-groups.ts

@@ -0,0 +1,216 @@
+/**
+ * Route decorator groups of the application (RFC 0001 §5.1): every `createRouteDecorator`
+ * definition, applied or not, the consistency of their options and the **required** groups.
+ *
+ * The http extension reports the inconsistencies (ZNIGHT005) and checks every route against the
+ * required groups (ZNIGHT023). Other extensions whose targets carry route decorators (WebSocket
+ * gateways, GraphQL root fields) call {@link requiredRouteGroups} to check their own targets with
+ * exactly the same groups, without reporting the inconsistencies a second time.
+ */
+import type { Diagnostic, Location, ValidateContext } from '@znight/compiler'
+import type { MetaEntry } from './model.ts'
+
+import { compareStrings } from '../path.ts'
+import { Codes, Ids } from './model.ts'
+import { parseRouteDecoratorOptions } from './route-decorators.ts'
+
+/** A route decorator definition of the application (`export const Roles = createRouteDecorator(...)`). */
+export interface RouteGroupMember {
+  /** Canonical identity of the decorator `const` (`src/auth/access.ts#Roles`). */
+  readonly identity: string
+  /** Name of the `const` (`Roles`). */
+  readonly name: string
+  readonly key: string
+  /** Decision group (`options.group ?? key`). */
+  readonly group: string
+  readonly required: boolean
+  /** Location of the definition. */
+  readonly definition: Location
+  /**
+   * A flag (`@Public()`): created without type argument, and applied without argument wherever it
+   * was seen. Decides how the decorator is suggested: `@Public()` or `@Roles(...)`.
+   */
+  readonly flag: boolean
+}
+
+/** A required route decorator group: every route-like target must carry a decision of it. */
+export interface RequiredRouteGroup {
+  /** Group name (`access`). */
+  readonly group: string
+  /** The decorators of the group, in source order (file, then position). Never empty. */
+  readonly decorators: readonly RouteGroupMember[]
+  /** The decorators as a hint: `@Public(), @Authenticated() or @Roles(...)`. */
+  readonly suggestion: string
+}
+
+/** Result of {@link analyzeRouteGroups}. */
+export interface RouteGroupsAnalysis {
+  /** Inconsistent definitions (ZNIGHT005), at the second definition; not reported. */
+  readonly conflicts: readonly Diagnostic[]
+  /** The required groups, in the order of their first definition by identity. */
+  readonly required: readonly RequiredRouteGroup[]
+}
+
+/** A definition while flags are computed. */
+type MutableMember = { -readonly [K in keyof RouteGroupMember]: RouteGroupMember[K] }
+
+/**
+ * Every route decorator definition, sorted by identity: the applied ones (`applied`, first usage
+ * wins) and, when the compiler provides `definitionsOf`, the ones applied nowhere (invalid ones are
+ * left to the usages, which report them).
+ */
+function routeDecoratorDefinitions(
+  ctx: Pick<ValidateContext<unknown>, 'definitionsOf'>,
+  applied: Iterable<MetaEntry>,
+): MutableMember[] {
+  const definitions = new Map<string, MutableMember>()
+  for (const entry of applied) {
+    const known = definitions.get(entry.identity)
+    if (known === undefined) {
+      definitions.set(entry.identity, {
+        identity: entry.identity,
+        name: entry.decorator,
+        key: entry.key,
+        group: entry.group,
+        required: entry.required,
+        definition: entry.definition,
+        flag: entry.value === true,
+      })
+    } else if (entry.value !== true) {
+      known.flag = false
+    }
+  }
+  // compilers before RFC 0001 have no definitionsOf: only applied decorators are known then
+  const all = typeof ctx.definitionsOf === 'function' ? ctx.definitionsOf(Ids.createRouteDecorator) : []
+  for (const found of all) {
+    const [keyArg, optionsArg, ...extra] = found.args
+    const key = keyArg?.evaluated === true ? keyArg.value : undefined
+    if (
+      typeof key !== 'string' ||
+      key === '' ||
+      extra.length > 0 ||
+      (optionsArg !== undefined && !optionsArg.evaluated)
+    ) {
+      continue
+    }
+    const parsed = parseRouteDecoratorOptions(key, optionsArg?.value)
+    if ('error' in parsed) {
+      continue
+    }
+    const flag = found.typeArgs.length === 0
+    const known = definitions.get(found.identity)
+    if (known !== undefined) {
+      known.flag &&= flag
+      continue
+    }
+    definitions.set(found.identity, {
+      identity: found.identity,
+      name: found.name,
+      key,
+      ...parsed,
+      definition: found.location,
+      flag,
+    })
+  }
+  return [...definitions.values()].sort((a, b) => compareStrings(a.identity, b.identity))
+}
+
+/**
+ * The route decorator groups of the application (RFC 0001 §5.1): every definition of a key must use
+ * the same options and the decorators of a group must agree on `required` (a conflict is returned
+ * at the second definition, which is then ignored); the required groups with their decorators.
+ * `applied` are the entries of the targets the caller analysed (their first usage of a decorator
+ * wins over its `definitionsOf` entry).
+ */
+export function analyzeRouteGroups(
+  ctx: Pick<ValidateContext<unknown>, 'definitionsOf'>,
+  applied: Iterable<MetaEntry>,
+): RouteGroupsAnalysis {
+  const definitions = routeDecoratorDefinitions(ctx, applied)
+  if (definitions.length === 0) {
+    return { conflicts: [], required: [] }
+  }
+  const conflicts: Diagnostic[] = []
+  const byKey = new Map<string, RouteGroupMember>()
+  const byGroup = new Map<string, RouteGroupMember>()
+  const members = new Map<string, RouteGroupMember[]>()
+  for (const definition of definitions) {
+    const sameKey = byKey.get(definition.key)
+    if (sameKey !== undefined && (sameKey.group !== definition.group || sameKey.required !== definition.required)) {
+      conflicts.push({
+        code: Codes.InvalidDecorator,
+        severity: 'error',
+        message: `The route decorator ${definition.name} defines the key "${definition.key}" with ${describeOptions(definition)}, but ${sameKey.name} defines it with ${describeOptions(sameKey)}`,
+        location: definition.definition,
+        hints: ['Every definition of a key must use the same options: share one definition'],
+        related: [{ message: `${sameKey.name} is defined here`, location: sameKey.definition }],
+      })
+      continue
+    }
+    const sameGroup = byGroup.get(definition.group)
+    if (sameGroup !== undefined && sameGroup.required !== definition.required) {
+      conflicts.push({
+        code: Codes.InvalidDecorator,
+        severity: 'error',
+        message: `The "${definition.group}" group is ${definition.required ? '' : 'not '}required for ${definition.name} but ${sameGroup.required ? '' : 'not '}required for ${sameGroup.name}`,
+        location: definition.definition,
+        hints: [`All the decorators of the "${definition.group}" group must agree on required`],
+        related: [{ message: `${sameGroup.name} is defined here`, location: sameGroup.definition }],
+      })
+      continue
+    }
+    byKey.set(definition.key, sameKey ?? definition)
+    byGroup.set(definition.group, sameGroup ?? definition)
+    const list = members.get(definition.group) ?? []
+    list.push(definition)
+    members.set(definition.group, list)
+  }
+  const required: RequiredRouteGroup[] = []
+  for (const first of byGroup.values()) {
+    if (!first.required) {
+      continue
+    }
+    // the decorators of the group in source order: `@Public(), @Authenticated() or @Roles(...)`
+    const decorators = [...(members.get(first.group) ?? [first])]
+      .sort((a, b) => compareStrings(a.definition.file, b.definition.file) || a.definition.start - b.definition.start)
+      .map(member => Object.freeze({ ...member }))
+    const usages = decorators.map(member => `@${member.name}(${member.flag ? '' : '...'})`)
+    const suggestion =
+      usages.length === 1 ? (usages[0] as string) : `${usages.slice(0, -1).join(', ')} or ${usages.at(-1) as string}`
+    required.push(Object.freeze({ group: first.group, decorators: Object.freeze(decorators), suggestion }))
+  }
+  return { conflicts, required }
+}
+
+/**
+ * The required route decorator groups of the application (RFC 0001): what every route-like target
+ * of another extension (a gateway, a GraphQL root field) must decide, exactly as HTTP routes must.
+ * A target without a decision of a returned group is **ZNIGHT023**, reported by the caller.
+ *
+ * `applied` are the route metadata entries the caller read on its own targets
+ * ({@link readRouteMeta}): they make decorators known even when the compiler has no
+ * `definitionsOf`, and refine how flags are suggested. Inconsistent definitions are left out and
+ * not reported here: the http extension reports them (ZNIGHT005) once.
+ *
+ * ```ts
+ * validate(ctx) {
+ *   const required = requiredRouteGroups(ctx, ctx.stored.flatMap(gateway => gateway.meta))
+ *   for (const gateway of ctx.stored)
+ *     for (const group of required)
+ *       if (!gateway.meta.some(entry => entry.group === group.group))
+ *         ctx.report({ code: 'ZNIGHT023', severity: 'error', message: `${gateway.name} has no "${group.group}" decision`,
+ *           location: gateway.location, hints: [`Add ${group.suggestion} to ${gateway.name}`] })
+ * }
+ * ```
+ */
+export function requiredRouteGroups(
+  ctx: ValidateContext<unknown>,
+  applied: Iterable<MetaEntry> = [],
+): readonly RequiredRouteGroup[] {
+  return analyzeRouteGroups(ctx, applied).required
+}
+
+function describeOptions(entry: RouteGroupMember): string {
+  const group = entry.group === entry.key ? 'no group' : `group "${entry.group}"`
+  return entry.required ? `${group}, required` : group
+}

package/src/compiler/validate.ts

@@ -7,10 +7,11 @@
 import type { Location, ValidateContext } from '@znight/compiler'
 import type { RoutePath } from '../path.ts'
 import type { HttpControllerData, HttpRouteData, MetaEntry } from './model.ts'
+import type { RequiredRouteGroup, RouteGroupMember } from './route-groups.ts'
 
 import { checkRoutePath, compareStrings, parseRoutePath, WILDCARD_PARAM } from '../path.ts'
-import { Codes, Ids } from './model.ts'
-import { parseRouteDecoratorOptions } from './route-decorators.ts'
+import { Codes } from './model.ts'
+import { analyzeRouteGroups } from './route-groups.ts'
 
 type Context = ValidateContext<HttpControllerData>
 
@@ -69,80 +70,12 @@ export function validateHttp(ctx: Context): void {
   validateDecisions(ctx, controllers)
 }
 
-/** A route decorator definition seen during the compile (applied, or found by `definitionsOf`). */
-interface Definition {
-  readonly identity: string
-  readonly name: string
-  readonly key: string
-  readonly group: string
-  readonly required: boolean
-  readonly definition: Location
-  /** A flag (`@Public()`): no type argument, or every usage without argument. */
-  flag: boolean
-}
-
-/**
- * Every route decorator definition, sorted by identity: the applied ones (first usage) and, when
- * the compiler provides `definitionsOf`, the ones applied nowhere (invalid ones are left to the
- * usages, which report them).
- */
-function routeDecoratorDefinitions(ctx: Context, controllers: readonly HttpControllerData[]): Definition[] {
-  const definitions = new Map<string, Definition>()
-  const visit = (entries: readonly MetaEntry[]): void => {
-    for (const entry of entries) {
-      const known = definitions.get(entry.identity)
-      if (known === undefined) {
-        definitions.set(entry.identity, {
-          identity: entry.identity,
-          name: entry.decorator,
-          key: entry.key,
-          group: entry.group,
-          required: entry.required,
-          definition: entry.definition,
-          flag: entry.value === true,
-        })
-      } else if (entry.value !== true) {
-        known.flag = false
-      }
-    }
-  }
+/** Every route metadata entry of the controllers: controller entries, then route entries. */
+function* appliedEntries(controllers: readonly HttpControllerData[]): Generator<MetaEntry> {
   for (const controller of controllers) {
-    visit(controller.meta)
-    for (const route of controller.routes) visit(route.meta)
-  }
-  // compilers before RFC 0001 have no definitionsOf: only applied decorators are known then
-  const all = typeof ctx.definitionsOf === 'function' ? ctx.definitionsOf(Ids.createRouteDecorator) : []
-  for (const found of all) {
-    const [keyArg, optionsArg, ...extra] = found.args
-    const key = keyArg?.evaluated === true ? keyArg.value : undefined
-    if (
-      typeof key !== 'string' ||
-      key === '' ||
-      extra.length > 0 ||
-      (optionsArg !== undefined && !optionsArg.evaluated)
-    ) {
-      continue
-    }
-    const parsed = parseRouteDecoratorOptions(key, optionsArg?.value)
-    if ('error' in parsed) {
-      continue
-    }
-    const flag = found.typeArgs.length === 0
-    const known = definitions.get(found.identity)
-    if (known !== undefined) {
-      known.flag &&= flag
-      continue
-    }
-    definitions.set(found.identity, {
-      identity: found.identity,
-      name: found.name,
-      key,
-      ...parsed,
-      definition: found.location,
-      flag,
-    })
+    yield* controller.meta
+    for (const route of controller.routes) yield* route.meta
   }
-  return [...definitions.values()].sort((a, b) => compareStrings(a.identity, b.identity))
 }
 
 /**
@@ -151,45 +84,10 @@ function routeDecoratorDefinitions(ctx: Context, controllers: readonly HttpContr
  * a decision of every required group, its own or its controller's (ZNIGHT023).
  */
 function validateDecisions(ctx: Context, controllers: readonly HttpControllerData[]): void {
-  const definitions = routeDecoratorDefinitions(ctx, controllers)
-  if (definitions.length === 0) {
-    return
-  }
-  const byKey = new Map<string, Definition>()
-  const byGroup = new Map<string, Definition>()
-  const members = new Map<string, Definition[]>()
-  for (const definition of definitions) {
-    const sameKey = byKey.get(definition.key)
-    if (sameKey !== undefined && (sameKey.group !== definition.group || sameKey.required !== definition.required)) {
-      ctx.report({
-        code: Codes.InvalidDecorator,
-        severity: 'error',
-        message: `The route decorator ${definition.name} defines the key "${definition.key}" with ${describeOptions(definition)}, but ${sameKey.name} defines it with ${describeOptions(sameKey)}`,
-        location: definition.definition,
-        hints: ['Every definition of a key must use the same options: share one definition'],
-        related: [{ message: `${sameKey.name} is defined here`, location: sameKey.definition }],
-      })
-      continue
-    }
-    const sameGroup = byGroup.get(definition.group)
-    if (sameGroup !== undefined && sameGroup.required !== definition.required) {
-      ctx.report({
-        code: Codes.InvalidDecorator,
-        severity: 'error',
-        message: `The "${definition.group}" group is ${definition.required ? '' : 'not '}required for ${definition.name} but ${sameGroup.required ? '' : 'not '}required for ${sameGroup.name}`,
-        location: definition.definition,
-        hints: [`All the decorators of the "${definition.group}" group must agree on required`],
-        related: [{ message: `${sameGroup.name} is defined here`, location: sameGroup.definition }],
-      })
-      continue
-    }
-    byKey.set(definition.key, sameKey ?? definition)
-    byGroup.set(definition.group, sameGroup ?? definition)
-    const list = members.get(definition.group) ?? []
-    list.push(definition)
-    members.set(definition.group, list)
+  const { conflicts, required } = analyzeRouteGroups(ctx, appliedEntries(controllers))
+  for (const conflict of conflicts) {
+    ctx.report(conflict)
   }
-  const required = [...byGroup.values()].filter(definition => definition.required)
   if (required.length === 0) {
     return
   }
@@ -201,23 +99,14 @@ function validateDecisions(ctx: Context, controllers: readonly HttpControllerDat
         if (decided.has(group.group)) {
           continue
         }
-        // the decorators of the group in source order: `@Public(), @Authenticated() or @Roles(...)`
-        const inOrder = [...(members.get(group.group) ?? [group])].sort(
-          (a, b) => compareStrings(a.definition.file, b.definition.file) || a.definition.start - b.definition.start,
-        )
-        const decorators = inOrder.map(definition => `@${definition.name}(${definition.flag ? '' : '...'})`)
-        const listed =
-          decorators.length === 1
-            ? (decorators[0] as string)
-            : `${decorators.slice(0, -1).join(', ')} or ${decorators.at(-1) as string}`
         ctx.report({
           code: Codes.MissingRouteDecision,
           severity: 'error',
           message: `Route ${route.method} ${route.fullPath} (${controller.displayName}.${route.handler}) has no "${group.group}" decision`,
           location: route.location,
-          hints: [`Add ${listed} to the route or to ${controller.displayName}`],
+          hints: [`Add ${group.suggestion} to the route or to ${controller.displayName}`],
           related: [
-            { message: `The "${group.group}" group is required`, location: (inOrder[0] ?? group).definition },
+            { message: `The "${group.group}" group is required`, location: firstDefinition(group) },
             { message: `${controller.displayName} is declared here`, location: controller.location },
           ],
         })
@@ -226,9 +115,9 @@ function validateDecisions(ctx: Context, controllers: readonly HttpControllerDat
   }
 }
 
-function describeOptions(entry: Definition): string {
-  const group = entry.group === entry.key ? 'no group' : `group "${entry.group}"`
-  return entry.required ? `${group}, required` : group
+/** Where the first decorator of a group (source order) is defined. */
+function firstDefinition(group: RequiredRouteGroup): Location {
+  return (group.decorators[0] as RouteGroupMember).definition
 }
 
 const GRAMMAR_HINTS: readonly string[] = [