ts-procedures 10.2.2 → 10.3.0

package/src/server/scope-name-collision.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from 'vitest'
+import { Procedures } from '../core/procedures.js'
+import { ProcedureRegistrationError } from '../core/errors.js'
+import { toPascalCase, versionedPascal } from '../naming.js'
+import type { RPCConfig } from './types.js'
+import type { AnyProcedureRegistration } from '../core/types.js'
+import { assertNoScopeNameCollisions, generatedRouteName } from './scope-name-collision.js'
+
+type Reg = AnyProcedureRegistration<any, any>
+
+describe('generatedRouteName — per-kind dispatch', () => {
+  // generatedRouteName routes each kind to the right shared naming primitive
+  // (versionedPascal for rpc/rpc-stream, toPascalCase for http kinds) — the same
+  // primitives the codegen emitters use, so the guard and codegen can't disagree.
+  test('rpc / rpc-stream match versionedPascal(name, version)', () => {
+    const cases: { name: string; version: number }[] = [
+      { name: 'get-task', version: 1 },
+      { name: 'getTask', version: 2 },
+      { name: 'log_out', version: 3 },
+      { name: 'Foo', version: 1 },
+    ]
+    for (const { name, version } of cases) {
+      const rpc = { name, kind: 'rpc', config: { version } } as unknown as Reg
+      const stream = { name, kind: 'rpc-stream', config: { version } } as unknown as Reg
+      expect(generatedRouteName(rpc)).toBe(versionedPascal(name, version))
+      expect(generatedRouteName(stream)).toBe(versionedPascal(name, version))
+    }
+  })
+
+  test('http / http-stream match toPascalCase(name), ignoring any version', () => {
+    for (const name of ['get-user', 'getUser', 'log out', 'list_items']) {
+      const http = { name, kind: 'http', config: { method: 'get', path: '/x', version: 9 } } as unknown as Reg
+      const httpStream = { name, kind: 'http-stream', config: { method: 'get', path: '/x' } } as unknown as Reg
+      expect(generatedRouteName(http)).toBe(toPascalCase(name))
+      expect(generatedRouteName(httpStream)).toBe(toPascalCase(name))
+    }
+  })
+
+  test('version 1 produces no V suffix; version > 1 does', () => {
+    const v1 = { name: 'Thing', kind: 'rpc', config: { version: 1 } } as unknown as Reg
+    const v2 = { name: 'Thing', kind: 'rpc', config: { version: 2 } } as unknown as Reg
+    expect(generatedRouteName(v1)).toBe('Thing')
+    expect(generatedRouteName(v2)).toBe('ThingV2')
+  })
+})
+
+describe('assertNoScopeNameCollisions', () => {
+  test('no-op when every procedure generates a distinct scoped name', () => {
+    const P = Procedures<object, RPCConfig>()
+    P.Create('GetTask', { scope: 'tasks', version: 1 }, async () => ({}))
+    P.Create('ListTasks', { scope: 'tasks', version: 1 }, async () => ({}))
+    expect(() => assertNoScopeNameCollisions(P.getProcedures())).not.toThrow()
+  })
+
+  test('same name in DIFFERENT scopes is allowed (separate scope files)', () => {
+    const A = Procedures<object, RPCConfig>()
+    A.Create('Get', { scope: 'users', version: 1 }, async () => ({}))
+    const B = Procedures<object, RPCConfig>()
+    B.Create('Get', { scope: 'orders', version: 1 }, async () => ({}))
+    expect(() => assertNoScopeNameCollisions([...A.getProcedures(), ...B.getProcedures()])).not.toThrow()
+  })
+
+  test('detects names that pascalize to the same identifier in one scope', () => {
+    const P = Procedures<object, RPCConfig>()
+    // distinct raw names → both register on the core registry...
+    P.Create('get-task', { scope: 'tasks', version: 1 }, async () => ({}))
+    P.Create('getTask', { scope: 'tasks', version: 1 }, async () => ({}))
+    // ...but both pascalize to "GetTask".
+    expect(() => assertNoScopeNameCollisions(P.getProcedures())).toThrow(ProcedureRegistrationError)
+    expect(() => assertNoScopeNameCollisions(P.getProcedures())).toThrow(/GetTask/)
+  })
+
+  test('detects the same (scope, name) contributed by two separate factories', () => {
+    const A = Procedures<object, RPCConfig>()
+    A.Create('LogOut', { scope: 'auth', version: 1 }, async () => ({}))
+    const B = Procedures<object, RPCConfig>()
+    B.Create('LogOut', { scope: 'auth', version: 1 }, async () => ({}))
+
+    const all = [...A.getProcedures(), ...B.getProcedures()]
+    expect(() => assertNoScopeNameCollisions(all)).toThrow(/Scope "auth".*LogOut/s)
+  })
+
+  test('version disambiguates: Foo@v1 and Foo@v2 (across factories) do not collide', () => {
+    // Same raw name can't register twice in one factory, but two factories can
+    // each contribute a "Foo" — distinct versions keep their generated names apart.
+    const A = Procedures<object, RPCConfig>()
+    A.Create('Foo', { scope: 's', version: 1 }, async () => ({}))
+    const B = Procedures<object, RPCConfig>()
+    B.Create('Foo', { scope: 's', version: 2 }, async () => ({}))
+    expect(() => assertNoScopeNameCollisions([...A.getProcedures(), ...B.getProcedures()])).not.toThrow()
+  })
+
+  test('version collision: Foo@v2 and FooV2@v1 both generate "FooV2"', () => {
+    const P = Procedures<object, RPCConfig>()
+    P.Create('Foo', { scope: 's', version: 2 }, async () => ({}))
+    P.Create('FooV2', { scope: 's', version: 1 }, async () => ({}))
+    expect(() => assertNoScopeNameCollisions(P.getProcedures())).toThrow(/FooV2/)
+  })
+
+  test('rpc and http procedures collide when they share scope + generated name', () => {
+    const A = Procedures<object, RPCConfig>()
+    A.Create('Thing', { scope: 'mix', version: 1 }, async () => ({}))
+    const B = Procedures<object, RPCConfig>()
+    B.CreateHttp('Thing', { scope: 'mix', path: '/thing', method: 'get' }, async () => undefined)
+    expect(() => assertNoScopeNameCollisions([...A.getProcedures(), ...B.getProcedures()])).toThrow(/Thing/)
+  })
+
+  test('procedures with no scope are grouped under "default" and can collide', () => {
+    const P = Procedures<object, RPCConfig>()
+    P.CreateHttp('do-thing', { path: '/a', method: 'get' }, async () => undefined)
+    P.CreateHttp('doThing', { path: '/b', method: 'get' }, async () => undefined)
+    expect(() => assertNoScopeNameCollisions(P.getProcedures())).toThrow(/Scope "default".*DoThing/s)
+  })
+
+  test('error message names both procedures and includes their definition sites', () => {
+    const P = Procedures<object, RPCConfig>()
+    P.Create('get-task', { scope: 'tasks', version: 1 }, async () => ({}))
+    P.Create('getTask', { scope: 'tasks', version: 1 }, async () => ({}))
+
+    let caught: ProcedureRegistrationError | undefined
+    try {
+      assertNoScopeNameCollisions(P.getProcedures())
+    } catch (err) {
+      caught = err as ProcedureRegistrationError
+    }
+    expect(caught).toBeInstanceOf(ProcedureRegistrationError)
+    expect(caught!.message).toContain('"get-task"')
+    expect(caught!.message).toContain('"getTask"')
+    expect(caught!.message).toContain('GetTask')
+    // definition site captured at registration flows into the trace
+    expect(caught!.message).toContain('scope-name-collision.test.ts')
+    expect(caught!.getDefinitionLocation()).toContain('scope-name-collision.test.ts')
+  })
+
+  test('reports every colliding group in one error', () => {
+    const P = Procedures<object, RPCConfig>()
+    P.Create('a-one', { scope: 's', version: 1 }, async () => ({}))
+    P.Create('aOne', { scope: 's', version: 1 }, async () => ({}))
+    P.Create('b-two', { scope: 's', version: 1 }, async () => ({}))
+    P.Create('bTwo', { scope: 's', version: 1 }, async () => ({}))
+
+    let message = ''
+    try {
+      assertNoScopeNameCollisions(P.getProcedures())
+    } catch (err) {
+      message = (err as Error).message
+    }
+    expect(message).toContain('AOne')
+    expect(message).toContain('BTwo')
+  })
+})

package/src/server/scope-name-collision.ts

@@ -0,0 +1,112 @@
+/**
+ * Server-start guard that mirrors the codegen TS emitter's per-scope name
+ * collision check (`src/codegen/emit/scope-file.ts`).
+ *
+ * The core registry only enforces that raw procedure NAMES are unique within a
+ * single factory. That misses two cases the client codegen rejects — and which
+ * therefore produce a server that boots happily but can never have a working
+ * generated client:
+ *
+ *   1. Two names in the same scope that PascalCase to the same identifier
+ *      (e.g. `get-task` and `getTask` → `GetTask`), and
+ *   2. The same `(scope, name)` registered across two different factories that
+ *      are mounted on one app (each factory has its own registry, so neither
+ *      duplicate check fires).
+ *
+ * Both collapse to a single generated type + callable key in the emitted client
+ * (duplicate identifier / duplicate object key), which is exactly what
+ * `emitScopeFile` throws on. We surface the same failure at server start, with a
+ * trace pointing at every colliding definition site, so it's caught in the
+ * server developer's own codebase instead of downstream at codegen time.
+ */
+import { ProcedureRegistrationError } from '../core/errors.js'
+import type { DefinitionInfo } from '../core/definition-site.js'
+import type { AnyProcedureRegistration } from '../core/types.js'
+import { normalizeScope, toPascalCase, versionedPascal } from '../naming.js'
+
+/**
+ * The identifier a procedure generates in the client. Built from the same
+ * shared naming primitives the codegen emitters use, so the two cannot disagree:
+ * - `rpc` / `rpc-stream` → `versionedPascal(name, version)` (V{n} when version > 1)
+ * - `http` / `http-stream` → `toPascalCase(name)` (no version suffix)
+ */
+export function generatedRouteName(procedure: AnyProcedureRegistration<any, any>): string {
+  if (procedure.kind === 'rpc' || procedure.kind === 'rpc-stream') {
+    return versionedPascal(procedure.name, (procedure.config as { version?: number }).version)
+  }
+  return toPascalCase(procedure.name)
+}
+
+/** The scope grouping key codegen would file this procedure under. */
+function scopeKeyOf(procedure: AnyProcedureRegistration<any, any>): string {
+  return normalizeScope((procedure.config as { scope?: string | string[] }).scope)
+}
+
+function definedAtString(info: DefinitionInfo | undefined): string {
+  const at = info?.definedAt
+  return at ? ` (defined at ${at.file}:${at.line}:${at.column})` : ''
+}
+
+/**
+ * Throws a {@link ProcedureRegistrationError} if any two procedures collapse to
+ * the same `(scope, generatedName)`. No-op when every procedure is distinct.
+ *
+ * Call this once with every procedure that will be served on a single app —
+ * including procedures contributed by separate factories — since cross-factory
+ * collisions are the case the per-factory registry can't see.
+ */
+export function assertNoScopeNameCollisions(
+  procedures: Iterable<AnyProcedureRegistration<any, any>>,
+): void {
+  // scopeKey → generatedName → procedures that produced it
+  const byScope = new Map<string, Map<string, AnyProcedureRegistration<any, any>[]>>()
+
+  for (const procedure of procedures) {
+    const scopeKey = scopeKeyOf(procedure)
+    const generated = generatedRouteName(procedure)
+    let byName = byScope.get(scopeKey)
+    if (byName === undefined) {
+      byName = new Map()
+      byScope.set(scopeKey, byName)
+    }
+    const existing = byName.get(generated)
+    if (existing === undefined) byName.set(generated, [procedure])
+    else existing.push(procedure)
+  }
+
+  const collisions: { scopeKey: string; generated: string; procs: AnyProcedureRegistration<any, any>[] }[] = []
+  for (const [scopeKey, byName] of byScope) {
+    for (const [generated, procs] of byName) {
+      if (procs.length > 1) collisions.push({ scopeKey, generated, procs })
+    }
+  }
+
+  if (collisions.length === 0) return
+
+  const details = collisions
+    .map(({ scopeKey, generated, procs }) => {
+      const lines = procs
+        .map((p) => `      - "${p.name}" (${p.kind})${definedAtString(p.definitionInfo)}`)
+        .join('\n')
+      return `  Scope "${scopeKey}" → generated name "${generated}":\n${lines}`
+    })
+    .join('\n')
+
+  // Anchor the error (and its appended definition-site frame) on the first
+  // colliding procedure; the message enumerates every collision.
+  const first = collisions[0]!.procs[0]!
+
+  throw new ProcedureRegistrationError(
+    first.name,
+    `Procedure name collision — the server cannot start.\n\n` +
+      `These procedures collapse to the same generated client identifier within the same scope. ` +
+      `The generated client would emit duplicate types and a duplicate callable key for each pair ` +
+      `(this is the same failure the codegen rejects), so the server refuses to start rather than ` +
+      `boot a config no client can be generated for:\n\n` +
+      `${details}\n\n` +
+      `Names are PascalCased per scope, so different raw names can still collide ` +
+      `(e.g. "get-task" and "getTask" both become "GetTask"). Rename one procedure in each pair, ` +
+      `or move it to a different scope, so every procedure in a scope generates a distinct name.`,
+    first.definitionInfo,
+  )
+}