@pikku/inspector 0.12.67 → 0.12.68

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.12.68
+
+### Patch Changes
+
+- ee9da9e: A `.transform()` in a schema used as a function's `input` now reports PKU491, naming the schema and the path to the transform, instead of surfacing downstream as PKU724 — the bad `#pikku/*` import error.
+- Updated dependencies [ee9da9e]
+- Updated dependencies [7a15c9c]
+- Updated dependencies [ee9da9e]
+  - @pikku/core@0.12.99
+
 ## 0.12.67
 
 ### Patch Changes

package/dist/error-codes.d.ts

@@ -65,6 +65,7 @@ export declare enum ErrorCode {
     AGENT_TOOL_MISSING_DESCRIPTION = "PKU154",
     AGENT_SCORER_NOT_FOUND = "PKU155",
     SCHEMA_AND_WIRING_COLOCATED = "PKU490",
+    SCHEMA_TRANSFORM_NOT_SUPPORTED = "PKU491",
     SERVICES_NOT_DESTRUCTURED = "PKU410",
     WIRES_NOT_DESTRUCTURED = "PKU411",
     FUNCTION_DYNAMIC_IMPORT = "PKU498",

package/dist/error-codes.js

@@ -84,6 +84,8 @@ export var ErrorCode;
     ErrorCode["AGENT_SCORER_NOT_FOUND"] = "PKU155";
     // File structure errors
     ErrorCode["SCHEMA_AND_WIRING_COLOCATED"] = "PKU490";
+    // Schema authoring errors
+    ErrorCode["SCHEMA_TRANSFORM_NOT_SUPPORTED"] = "PKU491";
     // Optimization diagnostics
     ErrorCode["SERVICES_NOT_DESTRUCTURED"] = "PKU410";
     ErrorCode["WIRES_NOT_DESTRUCTURED"] = "PKU411";

package/dist/utils/find-zod-transform.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Locate a `.transform()` anywhere inside a Zod schema.
+ *
+ * A transform is why a schema cannot be a function's `input`: the value the
+ * caller sends and the value the function receives are different, and a wire
+ * contract has to describe one shape. Zod says so twice, in two different
+ * places, and neither says it usefully on its own — `toJSONSchema` with
+ * `unrepresentable: 'any'` quietly yields `{}`, a schema that accepts
+ * everything, and `zodToTs` throws about TypeScript rather than about the
+ * wiring. Finding it up front lets the diagnostic name the schema, the path,
+ * and the call.
+ *
+ * Zod 4 models `x.transform(fn)` as a `pipe` whose `out` is a `transform`, so
+ * the walk looks for that node rather than for the method.
+ */
+/**
+ * The path to the first `.transform()` found — `''` when the transform is the
+ * schema itself, `'.user.email'` when it is nested — or `undefined` when there
+ * is none.
+ */
+export declare function findZodTransform(schema: unknown): string | undefined;

package/dist/utils/find-zod-transform.js

@@ -0,0 +1,93 @@
+/**
+ * Locate a `.transform()` anywhere inside a Zod schema.
+ *
+ * A transform is why a schema cannot be a function's `input`: the value the
+ * caller sends and the value the function receives are different, and a wire
+ * contract has to describe one shape. Zod says so twice, in two different
+ * places, and neither says it usefully on its own — `toJSONSchema` with
+ * `unrepresentable: 'any'` quietly yields `{}`, a schema that accepts
+ * everything, and `zodToTs` throws about TypeScript rather than about the
+ * wiring. Finding it up front lets the diagnostic name the schema, the path,
+ * and the call.
+ *
+ * Zod 4 models `x.transform(fn)` as a `pipe` whose `out` is a `transform`, so
+ * the walk looks for that node rather than for the method.
+ */
+/** Max nodes visited, so a pathological or cyclic schema cannot hang the walk. */
+const MAX_NODES = 10_000;
+const isNode = (value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value._zod?.def?.type === 'string';
+/**
+ * The path to the first `.transform()` found — `''` when the transform is the
+ * schema itself, `'.user.email'` when it is nested — or `undefined` when there
+ * is none.
+ */
+export function findZodTransform(schema) {
+    const seen = new Set();
+    let budget = MAX_NODES;
+    const walk = (node, path) => {
+        if (budget-- <= 0 || !isNode(node) || seen.has(node))
+            return undefined;
+        seen.add(node);
+        const def = node._zod.def;
+        if (def.type === 'transform')
+            return path;
+        const children = [];
+        switch (def.type) {
+            case 'object':
+            case 'interface':
+                for (const [key, child] of Object.entries(def.shape ?? {})) {
+                    children.push([child, `${path}.${key}`]);
+                }
+                break;
+            case 'array':
+            case 'set':
+                children.push([def.element, `${path}[]`]);
+                break;
+            case 'tuple':
+                for (const [i, child] of (def.items ?? []).entries()) {
+                    children.push([child, `${path}[${i}]`]);
+                }
+                if (def.rest)
+                    children.push([def.rest, `${path}[]`]);
+                break;
+            case 'union':
+                for (const [i, child] of (def.options ?? []).entries()) {
+                    children.push([child, `${path}|${i}`]);
+                }
+                break;
+            case 'intersection':
+                children.push([def.left, path], [def.right, path]);
+                break;
+            case 'record':
+            case 'map':
+                children.push([def.keyType, `${path}[key]`], [def.valueType, `${path}[]`]);
+                break;
+            case 'pipe':
+                // `.transform()` itself: report the pipe's own path, not `out`'s.
+                children.push([def.in, path], [def.out, path]);
+                break;
+            default:
+                // optional, nullable, default, prefault, nonoptional, readonly, catch,
+                // promise, lazy, success — every wrapper Zod spells `innerType`.
+                if (def.innerType)
+                    children.push([def.innerType, path]);
+                if (def.getter) {
+                    try {
+                        children.push([def.getter(), path]);
+                    }
+                    catch {
+                        // A lazy schema that cannot be forced tells us nothing; skip it.
+                    }
+                }
+        }
+        for (const [child, childPath] of children) {
+            const found = walk(child, childPath);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    return walk(schema, '');
+}

package/dist/utils/schema-generator.js

@@ -6,6 +6,7 @@ import { createGenerator, RootlessError } from 'ts-json-schema-generator';
 import { register } from 'tsx/esm/api';
 import * as z from 'zod';
 import { zodToTs, createAuxiliaryTypeStore } from 'zod-to-ts';
+import { findZodTransform } from './find-zod-transform.js';
 import { ErrorCode } from '../error-codes.js';
 import { generateCustomTypes } from './custom-types-generator.js';
 const PRIMITIVE_TYPES = new Set([
@@ -382,6 +383,16 @@ async function importWithRegister(sourceFile) {
     }
 }
 function processZodSchema(schemaName, zodSchema, schemas, typesMap, auxiliaryTypeStore, printer, fakeSourceFile, logger) {
+    const transformPath = findZodTransform(zodSchema);
+    if (transformPath !== undefined) {
+        const where = transformPath === '' ? 'the schema itself' : transformPath;
+        throw new Error(`[${ErrorCode.SCHEMA_TRANSFORM_NOT_SUPPORTED}] '${schemaName}' contains a .transform() at ${where}.\n` +
+            'A transform makes the value sent and the value received two different ' +
+            'shapes, and a wire contract describes one: it cannot be expressed in ' +
+            'JSON Schema or in the generated TypeScript.\n' +
+            'Validate with the plain schema and apply the transform inside the ' +
+            'function, or move it to the output type.');
+    }
     const schema = z.toJSONSchema(zodSchema, {
         unrepresentable: 'any',
         override: ({ zodSchema, jsonSchema }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.67",
+  "version": "0.12.68",
   "description": "TypeScript inspector for Pikku — discovers functions and wirings to drive code generation",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
@@ -45,10 +45,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.97"
+    "@pikku/core": "^0.12.99"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.97",
+    "@pikku/core": "^0.12.99",
     "@types/node": "^24.13.3"
   },
   "engines": {

package/src/error-codes.ts

@@ -98,6 +98,9 @@ export enum ErrorCode {
   // File structure errors
   SCHEMA_AND_WIRING_COLOCATED = 'PKU490',
 
+  // Schema authoring errors
+  SCHEMA_TRANSFORM_NOT_SUPPORTED = 'PKU491',
+
   // Optimization diagnostics
   SERVICES_NOT_DESTRUCTURED = 'PKU410',
   WIRES_NOT_DESTRUCTURED = 'PKU411',

package/src/utils/find-zod-transform.test.ts

@@ -0,0 +1,70 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import * as z from 'zod'
+import { findZodTransform } from './find-zod-transform.js'
+
+test('a schema with no transform is reported as clean', () => {
+  assert.equal(findZodTransform(z.object({ id: z.string() })), undefined)
+  assert.equal(findZodTransform(z.string().min(1).trim()), undefined)
+  // a refinement narrows the value, it does not change its shape
+  assert.equal(
+    findZodTransform(z.object({ id: z.string() }).refine(() => true)),
+    undefined
+  )
+})
+
+test('a transform on the schema itself is found at the root', () => {
+  assert.equal(
+    findZodTransform(z.object({ id: z.string() }).transform((v) => v)),
+    ''
+  )
+})
+
+test('a transform on a field is found by path', () => {
+  assert.equal(
+    findZodTransform(
+      z.object({
+        id: z.string(),
+        when: z.string().transform((s) => new Date(s)),
+      })
+    ),
+    '.when'
+  )
+})
+
+test('a transform is found through wrappers, arrays and unions', () => {
+  assert.equal(
+    findZodTransform(
+      z.object({ tags: z.array(z.string().transform((s) => s.trim())) })
+    ),
+    '.tags[]'
+  )
+  assert.equal(
+    findZodTransform(z.object({ n: z.string().transform(Number).optional() })),
+    '.n'
+  )
+  assert.equal(
+    findZodTransform(
+      z.object({ v: z.union([z.string(), z.number().transform(String)]) })
+    ),
+    '.v|1'
+  )
+  assert.equal(
+    findZodTransform(
+      z.object({
+        m: z.record(
+          z.string(),
+          z.string().transform((s) => s)
+        ),
+      })
+    ),
+    '.m[]'
+  )
+})
+
+test('a self-referencing schema terminates instead of recursing forever', () => {
+  const node: z.ZodType = z.lazy(() =>
+    z.object({ name: z.string(), children: z.array(node) })
+  )
+  assert.equal(findZodTransform(node), undefined)
+})

package/src/utils/find-zod-transform.ts

@@ -0,0 +1,103 @@
+/**
+ * Locate a `.transform()` anywhere inside a Zod schema.
+ *
+ * A transform is why a schema cannot be a function's `input`: the value the
+ * caller sends and the value the function receives are different, and a wire
+ * contract has to describe one shape. Zod says so twice, in two different
+ * places, and neither says it usefully on its own — `toJSONSchema` with
+ * `unrepresentable: 'any'` quietly yields `{}`, a schema that accepts
+ * everything, and `zodToTs` throws about TypeScript rather than about the
+ * wiring. Finding it up front lets the diagnostic name the schema, the path,
+ * and the call.
+ *
+ * Zod 4 models `x.transform(fn)` as a `pipe` whose `out` is a `transform`, so
+ * the walk looks for that node rather than for the method.
+ */
+
+/** Max nodes visited, so a pathological or cyclic schema cannot hang the walk. */
+const MAX_NODES = 10_000
+
+interface ZodNode {
+  _zod?: { def?: Record<string, any> }
+}
+
+const isNode = (value: unknown): value is ZodNode =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as ZodNode)._zod?.def?.type === 'string'
+
+/**
+ * The path to the first `.transform()` found — `''` when the transform is the
+ * schema itself, `'.user.email'` when it is nested — or `undefined` when there
+ * is none.
+ */
+export function findZodTransform(schema: unknown): string | undefined {
+  const seen = new Set<unknown>()
+  let budget = MAX_NODES
+
+  const walk = (node: unknown, path: string): string | undefined => {
+    if (budget-- <= 0 || !isNode(node) || seen.has(node)) return undefined
+    seen.add(node)
+
+    const def = node._zod!.def!
+    if (def.type === 'transform') return path
+
+    const children: Array<[unknown, string]> = []
+    switch (def.type) {
+      case 'object':
+      case 'interface':
+        for (const [key, child] of Object.entries(def.shape ?? {})) {
+          children.push([child, `${path}.${key}`])
+        }
+        break
+      case 'array':
+      case 'set':
+        children.push([def.element, `${path}[]`])
+        break
+      case 'tuple':
+        for (const [i, child] of (def.items ?? []).entries()) {
+          children.push([child, `${path}[${i}]`])
+        }
+        if (def.rest) children.push([def.rest, `${path}[]`])
+        break
+      case 'union':
+        for (const [i, child] of (def.options ?? []).entries()) {
+          children.push([child, `${path}|${i}`])
+        }
+        break
+      case 'intersection':
+        children.push([def.left, path], [def.right, path])
+        break
+      case 'record':
+      case 'map':
+        children.push(
+          [def.keyType, `${path}[key]`],
+          [def.valueType, `${path}[]`]
+        )
+        break
+      case 'pipe':
+        // `.transform()` itself: report the pipe's own path, not `out`'s.
+        children.push([def.in, path], [def.out, path])
+        break
+      default:
+        // optional, nullable, default, prefault, nonoptional, readonly, catch,
+        // promise, lazy, success — every wrapper Zod spells `innerType`.
+        if (def.innerType) children.push([def.innerType, path])
+        if (def.getter) {
+          try {
+            children.push([def.getter(), path])
+          } catch {
+            // A lazy schema that cannot be forced tells us nothing; skip it.
+          }
+        }
+    }
+
+    for (const [child, childPath] of children) {
+      const found = walk(child, childPath)
+      if (found !== undefined) return found
+    }
+    return undefined
+  }
+
+  return walk(schema, '')
+}

package/src/utils/schema-generator.test.ts

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict'
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
+import { fileURLToPath } from 'url'
 
 import { getInitialInspectorState } from '../inspector.js'
 import { generateAllSchemas, schemaRuntimeFile } from './schema-generator.js'
@@ -223,3 +224,49 @@ describe('schemaRuntimeFile', () => {
     assert.equal(schemaRuntimeFile(orphan), orphan)
   })
 })
+
+describe('a Zod schema that cannot be a wire contract', () => {
+  test('names .transform() and its own error code, not a downstream one', async () => {
+    // A transform used to surface as PKU724 — the *bad `#pikku/*` import* error
+    // — because the schema failed to convert, its generated leaf never got
+    // written, and the type that leaf feeds resolved to an error type. The
+    // message sent you to an import block that was fine.
+    // Inside the package, so the fixture's `import 'zod'` resolves the same
+    // way a project's would; a tmpdir has no node_modules above it.
+    const dir = mkdtempSync(
+      join(fileURLToPath(new URL('../../', import.meta.url)), '.zod-transform-')
+    )
+    try {
+      const file = join(dir, 'schema.ts')
+      writeFileSync(
+        file,
+        `import * as z from 'zod'\n` +
+          `export const CreateAssessment = z.object({ patientId: z.string(), when: z.string().transform((s) => new Date(s)) })\n`
+      )
+      const state = getInitialInspectorState(dir) as any
+      state.schemaLookup.set('CreateAssessmentInput', {
+        variableName: 'CreateAssessment',
+        sourceFile: file,
+        vendor: 'zod',
+      })
+
+      const errors: string[] = []
+      await assert.rejects(() =>
+        generateAllSchemas(
+          { ...logger, error: (m: string) => errors.push(m) },
+          { tsconfig: join(projectDir, 'tsconfig.json') },
+          state
+        )
+      )
+
+      const reported = errors.join('\n')
+      assert.match(reported, /PKU491/)
+      assert.match(reported, /CreateAssessmentInput/)
+      assert.match(reported, /\.transform\(\)/)
+      assert.match(reported, /\.when/)
+      assert.doesNotMatch(reported, /PKU724/)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/utils/schema-generator.ts

@@ -12,6 +12,7 @@ import { createGenerator, RootlessError } from 'ts-json-schema-generator'
 import { register } from 'tsx/esm/api'
 import * as z from 'zod'
 import { zodToTs, createAuxiliaryTypeStore } from 'zod-to-ts'
+import { findZodTransform } from './find-zod-transform.js'
 import type { FunctionsMeta } from '@pikku/core/services'
 import type { JSONValue } from '@pikku/core/utils'
 import type { HTTPWiringsMeta } from '@pikku/core/http'
@@ -508,6 +509,19 @@ function processZodSchema(
   fakeSourceFile: ts.SourceFile,
   logger: InspectorLogger
 ): void {
+  const transformPath = findZodTransform(zodSchema)
+  if (transformPath !== undefined) {
+    const where = transformPath === '' ? 'the schema itself' : transformPath
+    throw new Error(
+      `[${ErrorCode.SCHEMA_TRANSFORM_NOT_SUPPORTED}] '${schemaName}' contains a .transform() at ${where}.\n` +
+        'A transform makes the value sent and the value received two different ' +
+        'shapes, and a wire contract describes one: it cannot be expressed in ' +
+        'JSON Schema or in the generated TypeScript.\n' +
+        'Validate with the plain schema and apply the transform inside the ' +
+        'function, or move it to the output type.'
+    )
+  }
+
   const schema = z.toJSONSchema(zodSchema, {
     unrepresentable: 'any',
     override: ({ zodSchema, jsonSchema }) => {