openapi-typesafe 1.0.0-rc.3 → 1.0.0-rc.5

package/dist/api/openapi-ts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"openapi-ts.mjs","sources":["../../src/api/openapi-ts.ts"],"sourcesContent":["import { createRedoclySchemaLoader } from \"../adapters/redocly-loader/redocly-schema-loader.js\";\nimport { withStackOverflowReported } from \"../application/stack-overflow.js\";\nimport type { IrDeclaration } from \"../domain/ir/nodes.js\";\nimport type { GeneratorOptions, SchemaSource } from \"../types.js\";\nimport {\n  DEFAULT_REMOTE_DOCUMENT_LIMITS,\n  defaultDeprecationReporter,\n  defaultLogger,\n  defaultRedoclyConfig,\n  monotonicNow,\n  REMOTE_REF_TIMEOUT_MS,\n} from \"./default-ports.js\";\nimport { createDocumentRun, type GeneratorPorts } from \"./document-run.js\";\nimport transformSchema from \"./transform-schema.js\";\n\n/**\n * The Node API's composition root (ENGINEERING_PLAN 4.5): `openapiTS` wires the default adapters;\n * `generateDeclarations` runs with any ports, which is how the CLI calls it.\n */\n\n/** Load, validate and bundle the source, then transform it into IR declarations. */\nexport async function generateDeclarations(\n  source: SchemaSource,\n  options: GeneratorOptions,\n  ports: GeneratorPorts,\n): Promise<IrDeclaration[]> {\n  const { schema, ctx } = await createDocumentRun(source, options, ports);\n  const startedAt = ports.now();\n  const result = withStackOverflowReported(\"transform\", () => transformSchema(schema, ctx));\n  ports.logger.debug(\n    \"Completed AST transformation for entire document\",\n    \"ts\",\n    ports.now() - startedAt,\n  );\n  return result;\n}\n\n/**\n * The default ports: the terminal logger, Node.js deprecation warnings, the given or default\n * Redocly config, Redocly loading.\n */\nexport async function defaultGeneratorPorts(options: GeneratorOptions): Promise<GeneratorPorts> {\n  const logger = defaultLogger(options.silent ?? false);\n  const redoc = options.redocly ?? (await defaultRedoclyConfig());\n  const loader = createRedoclySchemaLoader({\n    redoc,\n    logger,\n    now: monotonicNow,\n    remoteRefTimeoutMs: REMOTE_REF_TIMEOUT_MS,\n    remoteDocumentLimits: DEFAULT_REMOTE_DOCUMENT_LIMITS,\n  });\n  return { loader, logger, deprecations: defaultDeprecationReporter(), redoc, now: monotonicNow };\n}\n\n/**\n * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)\n * @param {string|URL|object|Readable} source OpenAPI schema source:\n *   - YAML: string\n *   - JSON: parsed object\n *   - URL: URL to a YAML or JSON file (local or remote)\n *   - Readable: Readable stream of YAML or JSON\n */\nexport default async function openapiTS(\n  source: SchemaSource,\n  options: GeneratorOptions = {},\n): Promise<IrDeclaration[]> {\n  return generateDeclarations(source, options, await defaultGeneratorPorts(options));\n}\n"],"names":[],"mappings":";;;;;;AAqBA,eAAsB,oBAAA,CACpB,MAAA,EACA,OAAA,EACA,KAAA,EAC0B;AAC1B,EAAA,MAAM,EAAE,QAAQ,GAAA,EAAI,GAAI,MAAM,iBAAA,CAAkB,MAAA,EAAQ,SAAS,KAAK,CAAA;AACtE,EAAA,MAAM,SAAA,GAAY,MAAM,GAAA,EAAI;AAC5B,EAAA,MAAM,SAAS,yBAAA,CAA0B,WAAA,EAAa,MAAM,eAAA,CAAgB,MAAA,EAAQ,GAAG,CAAC,CAAA;AACxF,EAAA,KAAA,CAAM,MAAA,CAAO,KAAA;AAAA,IACX,kDAAA;AAAA,IACA,IAAA;AAAA,IACA,KAAA,CAAM,KAAI,GAAI;AAAA,GAChB;AACA,EAAA,OAAO,MAAA;AACT;AAMA,eAAsB,sBAAsB,OAAA,EAAoD;AAC9F,EAAA,MAAM,MAAA,GAAS,aAAA,CAAc,OAAA,CAAQ,MAAA,IAAU,KAAK,CAAA;AACpD,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,OAAA,IAAY,MAAM,oBAAA,EAAqB;AAC7D,EAAA,MAAM,SAAS,yBAAA,CAA0B;AAAA,IACvC,KAAA;AAAA,IACA,MAAA;AAAA,IACA,GAAA,EAAK,YAAA;AAAA,IACL,kBAAA,EAAoB,qBAAA;AAAA,IACpB,oBAAA,EAAsB;AAAA,GACvB,CAAA;AACD,EAAA,OAAO,EAAE,QAAQ,MAAA,EAAQ,YAAA,EAAc,4BAA2B,EAAG,KAAA,EAAO,KAAK,YAAA,EAAa;AAChG;AAUA,eAA8B,SAAA,CAC5B,MAAA,EACA,OAAA,GAA4B,EAAC,EACH;AAC1B,EAAA,OAAO,qBAAqB,MAAA,EAAQ,OAAA,EAAS,MAAM,qBAAA,CAAsB,OAAO,CAAC,CAAA;AACnF;;"}
+{"version":3,"file":"openapi-ts.mjs","sources":["../../src/api/openapi-ts.ts"],"sourcesContent":["import { createRedoclySchemaLoader } from \"../adapters/redocly-loader/redocly-schema-loader.js\";\nimport type { Logger } from \"../application/ports/logger.js\";\nimport { withStackOverflowReported } from \"../application/stack-overflow.js\";\nimport type { IrDeclaration } from \"../domain/ir/nodes.js\";\nimport type { GeneratorOptions, SchemaSource } from \"../types.js\";\nimport {\n  DEFAULT_REMOTE_DOCUMENT_LIMITS,\n  defaultDeprecationReporter,\n  defaultLogger,\n  defaultRedoclyConfig,\n  monotonicNow,\n  REMOTE_REF_TIMEOUT_MS,\n} from \"./default-ports.js\";\nimport { createDocumentRun, type GeneratorPorts } from \"./document-run.js\";\nimport transformSchema from \"./transform-schema.js\";\n\n/**\n * The Node API's composition root (ENGINEERING_PLAN 4.5): `openapiTS` wires the default adapters;\n * `generateDeclarations` runs with any ports, which is how the CLI calls it.\n */\n\n/** The declarations of one document, and the local files it was read from. */\nexport interface GeneratedDocument {\n  readonly declarations: IrDeclaration[];\n  readonly localFiles: readonly URL[];\n}\n\n/** Load, validate and bundle the source, then transform it into IR declarations. */\nexport async function generateDocument(\n  source: SchemaSource,\n  options: GeneratorOptions,\n  ports: GeneratorPorts,\n): Promise<GeneratedDocument> {\n  const { schema, localFiles, ctx } = await createDocumentRun(source, options, ports);\n  const startedAt = ports.now();\n  const declarations = withStackOverflowReported(\"transform\", () => transformSchema(schema, ctx));\n  ports.logger.debug(\n    \"Completed AST transformation for entire document\",\n    \"ts\",\n    ports.now() - startedAt,\n  );\n  return { declarations, localFiles };\n}\n\n/** As `generateDocument`, the declarations only. */\nexport async function generateDeclarations(\n  source: SchemaSource,\n  options: GeneratorOptions,\n  ports: GeneratorPorts,\n): Promise<IrDeclaration[]> {\n  return (await generateDocument(source, options, ports)).declarations;\n}\n\n/**\n * The default ports: the terminal logger, Node.js deprecation warnings, the given or default\n * Redocly config, Redocly loading. A given `logger` takes every line, the loader's included.\n */\nexport async function defaultGeneratorPorts(\n  options: GeneratorOptions,\n  logger: Logger = defaultLogger(options.silent ?? false),\n): Promise<GeneratorPorts> {\n  const redoc = options.redocly ?? (await defaultRedoclyConfig());\n  const loader = createRedoclySchemaLoader({\n    redoc,\n    logger,\n    now: monotonicNow,\n    remoteRefTimeoutMs: REMOTE_REF_TIMEOUT_MS,\n    remoteDocumentLimits: DEFAULT_REMOTE_DOCUMENT_LIMITS,\n  });\n  return { loader, logger, deprecations: defaultDeprecationReporter(), redoc, now: monotonicNow };\n}\n\n/**\n * Convert an OpenAPI schema to TypeScript declarations (IR nodes; print them with `astToString`)\n * @param {string|URL|object|Readable} source OpenAPI schema source:\n *   - YAML: string\n *   - JSON: parsed object\n *   - URL: URL to a YAML or JSON file (local or remote)\n *   - Readable: Readable stream of YAML or JSON\n */\nexport default async function openapiTS(\n  source: SchemaSource,\n  options: GeneratorOptions = {},\n): Promise<IrDeclaration[]> {\n  return generateDeclarations(source, options, await defaultGeneratorPorts(options));\n}\n"],"names":[],"mappings":";;;;;;AA4BA,eAAsB,gBAAA,CACpB,MAAA,EACA,OAAA,EACA,KAAA,EAC4B;AAC5B,EAAA,MAAM,EAAE,QAAQ,UAAA,EAAY,GAAA,KAAQ,MAAM,iBAAA,CAAkB,MAAA,EAAQ,OAAA,EAAS,KAAK,CAAA;AAClF,EAAA,MAAM,SAAA,GAAY,MAAM,GAAA,EAAI;AAC5B,EAAA,MAAM,eAAe,yBAAA,CAA0B,WAAA,EAAa,MAAM,eAAA,CAAgB,MAAA,EAAQ,GAAG,CAAC,CAAA;AAC9F,EAAA,KAAA,CAAM,MAAA,CAAO,KAAA;AAAA,IACX,kDAAA;AAAA,IACA,IAAA;AAAA,IACA,KAAA,CAAM,KAAI,GAAI;AAAA,GAChB;AACA,EAAA,OAAO,EAAE,cAAc,UAAA,EAAW;AACpC;AAGA,eAAsB,oBAAA,CACpB,MAAA,EACA,OAAA,EACA,KAAA,EAC0B;AAC1B,EAAA,OAAA,CAAQ,MAAM,gBAAA,CAAiB,MAAA,EAAQ,OAAA,EAAS,KAAK,CAAA,EAAG,YAAA;AAC1D;AAMA,eAAsB,sBACpB,OAAA,EACA,MAAA,GAAiB,cAAc,OAAA,CAAQ,MAAA,IAAU,KAAK,CAAA,EAC7B;AACzB,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,OAAA,IAAY,MAAM,oBAAA,EAAqB;AAC7D,EAAA,MAAM,SAAS,yBAAA,CAA0B;AAAA,IACvC,KAAA;AAAA,IACA,MAAA;AAAA,IACA,GAAA,EAAK,YAAA;AAAA,IACL,kBAAA,EAAoB,qBAAA;AAAA,IACpB,oBAAA,EAAsB;AAAA,GACvB,CAAA;AACD,EAAA,OAAO,EAAE,QAAQ,MAAA,EAAQ,YAAA,EAAc,4BAA2B,EAAG,KAAA,EAAO,KAAK,YAAA,EAAa;AAChG;AAUA,eAA8B,SAAA,CAC5B,MAAA,EACA,OAAA,GAA4B,EAAC,EACH;AAC1B,EAAA,OAAO,qBAAqB,MAAA,EAAQ,OAAA,EAAS,MAAM,qBAAA,CAAsB,OAAO,CAAC,CAAA;AACnF;;"}

package/dist/api/ref-limit-options.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+const path = require('node:path');
+const node_url = require('node:url');
+const errors = require('../domain/errors.cjs');
+const locationText = require('../domain/location-text.cjs');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+const path__default = /*#__PURE__*/_interopDefaultCompat(path);
+
+const FILE_PROTOCOL = "file:";
+function kindOf(value) {
+  if (value instanceof URL) {
+    return `a ${value.protocol} URL`;
+  }
+  if (Array.isArray(value)) {
+    return "a list";
+  }
+  return value === null ? "null" : `a ${typeof value}`;
+}
+function optionInvalid(option, expected, got) {
+  return new errors.OpenAPITypesafeError({
+    code: errors.ERROR_CODES.OPTION_INVALID,
+    message: `The ${option} option must be ${expected}; got ${got}.`,
+    details: { option }
+  });
+}
+const LOCAL_ROOT_EXPECTED = "a directory path or a file: URL";
+function localRootUrlOf(value, cwd) {
+  if (!locationText.hasUrlScheme(value)) {
+    return node_url.pathToFileURL(path__default.resolve(node_url.fileURLToPath(cwd), value));
+  }
+  return URL.parse(value, cwd.href) ?? void 0;
+}
+function localRootOf(value, cwd) {
+  const root = typeof value === "string" ? localRootUrlOf(value, cwd) : value;
+  if (root instanceof URL && root.protocol === FILE_PROTOCOL) {
+    return root;
+  }
+  const got = root === void 0 ? "a string that is no valid URL" : kindOf(root);
+  throw optionInvalid("localRefRoot", LOCAL_ROOT_EXPECTED, got);
+}
+function remoteHostsOf(value) {
+  if (!Array.isArray(value)) {
+    throw optionInvalid("remoteRefHosts", "a list of hosts", kindOf(value));
+  }
+  const other = value.find((entry) => typeof entry !== "string");
+  if (other !== void 0) {
+    throw optionInvalid("remoteRefHosts", "a list of hosts", `a list with ${kindOf(other)}`);
+  }
+  return value;
+}
+function refAccessOf(options, cwd) {
+  const { localRefRoot, remoteRefHosts } = options;
+  return {
+    ...localRefRoot === void 0 ? {} : { localRoot: localRootOf(localRefRoot, cwd) },
+    ...remoteRefHosts === void 0 ? {} : { remoteHosts: remoteHostsOf(remoteRefHosts) }
+  };
+}
+
+exports.refAccessOf = refAccessOf;
+//# sourceMappingURL=ref-limit-options.cjs.map

package/dist/api/ref-limit-options.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-limit-options.cjs","sources":["../../src/api/ref-limit-options.ts"],"sourcesContent":["import path from \"node:path\";\nimport { fileURLToPath, pathToFileURL } from \"node:url\";\nimport type { RefAccess } from \"../application/ports/schema-loader.js\";\nimport { ERROR_CODES, OpenAPITypesafeError } from \"../domain/errors.js\";\nimport { hasUrlScheme } from \"../domain/location-text.js\";\nimport type { GeneratorOptions } from \"../types.js\";\n\n/**\n * The `$ref` limits of the options (threat model R1, R2, ADR-017), checked before anything loads.\n * A value of another type from JavaScript (`remoteRefHosts: \"a.com\"`, `localRefRoot: new\n * URL(\"https://…\")`) used to fail later as an error of the document.\n */\n\nconst FILE_PROTOCOL = \"file:\";\n\n/** What a value is, for the error; a URL is named by its protocol only, as it may hold secrets. */\nfunction kindOf(value: unknown): string {\n  if (value instanceof URL) {\n    return `a ${value.protocol} URL`;\n  }\n  if (Array.isArray(value)) {\n    return \"a list\";\n  }\n  return value === null ? \"null\" : `a ${typeof value}`;\n}\n\nfunction optionInvalid(option: string, expected: string, got: string): OpenAPITypesafeError {\n  return new OpenAPITypesafeError({\n    code: ERROR_CODES.OPTION_INVALID,\n    message: `The ${option} option must be ${expected}; got ${got}.`,\n    details: { option },\n  });\n}\n\nconst LOCAL_ROOT_EXPECTED = \"a directory path or a file: URL\";\n\n/**\n * A string as the CLI reads `--local-ref-root`: a URL when it has a scheme (`file:///specs/`),\n * else a path that resolves against the cwd. Undefined when it does not parse as a URL.\n */\nfunction localRootUrlOf(value: string, cwd: URL): URL | undefined {\n  if (!hasUrlScheme(value)) {\n    return pathToFileURL(path.resolve(fileURLToPath(cwd), value));\n  }\n  return URL.parse(value, cwd.href) ?? undefined;\n}\n\n/** The local root as a `file:` URL; the option is set, so it is not undefined. */\nfunction localRootOf(value: unknown, cwd: URL): URL {\n  const root = typeof value === \"string\" ? localRootUrlOf(value, cwd) : value;\n  if (root instanceof URL && root.protocol === FILE_PROTOCOL) {\n    return root;\n  }\n  const got = root === undefined ? \"a string that is no valid URL\" : kindOf(root);\n  throw optionInvalid(\"localRefRoot\", LOCAL_ROOT_EXPECTED, got);\n}\n\nfunction remoteHostsOf(value: unknown): readonly string[] {\n  if (!Array.isArray(value)) {\n    throw optionInvalid(\"remoteRefHosts\", \"a list of hosts\", kindOf(value));\n  }\n  const other = value.find((entry) => typeof entry !== \"string\");\n  if (other !== undefined) {\n    throw optionInvalid(\"remoteRefHosts\", \"a list of hosts\", `a list with ${kindOf(other)}`);\n  }\n  return value;\n}\n\n/** The limits of the options; fails with `OPTION_INVALID` for a value of another type. */\nexport function refAccessOf(options: GeneratorOptions, cwd: URL): RefAccess {\n  const { localRefRoot, remoteRefHosts } = options;\n  return {\n    ...(localRefRoot === undefined ? {} : { localRoot: localRootOf(localRefRoot, cwd) }),\n    ...(remoteRefHosts === undefined ? {} : { remoteHosts: remoteHostsOf(remoteRefHosts) }),\n  };\n}\n"],"names":["OpenAPITypesafeError","ERROR_CODES","hasUrlScheme","pathToFileURL","path","fileURLToPath"],"mappings":";;;;;;;;;;;AAaA,MAAM,aAAA,GAAgB,OAAA;AAGtB,SAAS,OAAO,KAAA,EAAwB;AACtC,EAAA,IAAI,iBAAiB,GAAA,EAAK;AACxB,IAAA,OAAO,CAAA,EAAA,EAAK,MAAM,QAAQ,CAAA,IAAA,CAAA;AAAA,EAC5B;AACA,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACxB,IAAA,OAAO,QAAA;AAAA,EACT;AACA,EAAA,OAAO,KAAA,KAAU,IAAA,GAAO,MAAA,GAAS,CAAA,EAAA,EAAK,OAAO,KAAK,CAAA,CAAA;AACpD;AAEA,SAAS,aAAA,CAAc,MAAA,EAAgB,QAAA,EAAkB,GAAA,EAAmC;AAC1F,EAAA,OAAO,IAAIA,2BAAA,CAAqB;AAAA,IAC9B,MAAMC,kBAAA,CAAY,cAAA;AAAA,IAClB,SAAS,CAAA,IAAA,EAAO,MAAM,CAAA,gBAAA,EAAmB,QAAQ,SAAS,GAAG,CAAA,CAAA,CAAA;AAAA,IAC7D,OAAA,EAAS,EAAE,MAAA;AAAO,GACnB,CAAA;AACH;AAEA,MAAM,mBAAA,GAAsB,iCAAA;AAM5B,SAAS,cAAA,CAAe,OAAe,GAAA,EAA2B;AAChE,EAAA,IAAI,CAACC,yBAAA,CAAa,KAAK,CAAA,EAAG;AACxB,IAAA,OAAOC,uBAAcC,aAAA,CAAK,OAAA,CAAQC,uBAAc,GAAG,CAAA,EAAG,KAAK,CAAC,CAAA;AAAA,EAC9D;AACA,EAAA,OAAO,GAAA,CAAI,KAAA,CAAM,KAAA,EAAO,GAAA,CAAI,IAAI,CAAA,IAAK,MAAA;AACvC;AAGA,SAAS,WAAA,CAAY,OAAgB,GAAA,EAAe;AAClD,EAAA,MAAM,OAAO,OAAO,KAAA,KAAU,WAAW,cAAA,CAAe,KAAA,EAAO,GAAG,CAAA,GAAI,KAAA;AACtE,EAAA,IAAI,IAAA,YAAgB,GAAA,IAAO,IAAA,CAAK,QAAA,KAAa,aAAA,EAAe;AAC1D,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,MAAM,GAAA,GAAM,IAAA,KAAS,MAAA,GAAY,+BAAA,GAAkC,OAAO,IAAI,CAAA;AAC9E,EAAA,MAAM,aAAA,CAAc,cAAA,EAAgB,mBAAA,EAAqB,GAAG,CAAA;AAC9D;AAEA,SAAS,cAAc,KAAA,EAAmC;AACxD,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACzB,IAAA,MAAM,aAAA,CAAc,gBAAA,EAAkB,iBAAA,EAAmB,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,EACxE;AACA,EAAA,MAAM,QAAQ,KAAA,CAAM,IAAA,CAAK,CAAC,KAAA,KAAU,OAAO,UAAU,QAAQ,CAAA;AAC7D,EAAA,IAAI,UAAU,MAAA,EAAW;AACvB,IAAA,MAAM,cAAc,gBAAA,EAAkB,iBAAA,EAAmB,eAAe,MAAA,CAAO,KAAK,CAAC,CAAA,CAAE,CAAA;AAAA,EACzF;AACA,EAAA,OAAO,KAAA;AACT;AAGO,SAAS,WAAA,CAAY,SAA2B,GAAA,EAAqB;AAC1E,EAAA,MAAM,EAAE,YAAA,EAAc,cAAA,EAAe,GAAI,OAAA;AACzC,EAAA,OAAO;AAAA,IACL,GAAI,YAAA,KAAiB,MAAA,GAAY,EAAC,GAAI,EAAE,SAAA,EAAW,WAAA,CAAY,YAAA,EAAc,GAAG,CAAA,EAAE;AAAA,IAClF,GAAI,mBAAmB,MAAA,GAAY,KAAK,EAAE,WAAA,EAAa,aAAA,CAAc,cAAc,CAAA;AAAE,GACvF;AACF;;"}

package/dist/api/ref-limit-options.mjs

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { OpenAPITypesafeError, ERROR_CODES } from '../domain/errors.mjs';
+import { hasUrlScheme } from '../domain/location-text.mjs';
+
+const FILE_PROTOCOL = "file:";
+function kindOf(value) {
+  if (value instanceof URL) {
+    return `a ${value.protocol} URL`;
+  }
+  if (Array.isArray(value)) {
+    return "a list";
+  }
+  return value === null ? "null" : `a ${typeof value}`;
+}
+function optionInvalid(option, expected, got) {
+  return new OpenAPITypesafeError({
+    code: ERROR_CODES.OPTION_INVALID,
+    message: `The ${option} option must be ${expected}; got ${got}.`,
+    details: { option }
+  });
+}
+const LOCAL_ROOT_EXPECTED = "a directory path or a file: URL";
+function localRootUrlOf(value, cwd) {
+  if (!hasUrlScheme(value)) {
+    return pathToFileURL(path.resolve(fileURLToPath(cwd), value));
+  }
+  return URL.parse(value, cwd.href) ?? void 0;
+}
+function localRootOf(value, cwd) {
+  const root = typeof value === "string" ? localRootUrlOf(value, cwd) : value;
+  if (root instanceof URL && root.protocol === FILE_PROTOCOL) {
+    return root;
+  }
+  const got = root === void 0 ? "a string that is no valid URL" : kindOf(root);
+  throw optionInvalid("localRefRoot", LOCAL_ROOT_EXPECTED, got);
+}
+function remoteHostsOf(value) {
+  if (!Array.isArray(value)) {
+    throw optionInvalid("remoteRefHosts", "a list of hosts", kindOf(value));
+  }
+  const other = value.find((entry) => typeof entry !== "string");
+  if (other !== void 0) {
+    throw optionInvalid("remoteRefHosts", "a list of hosts", `a list with ${kindOf(other)}`);
+  }
+  return value;
+}
+function refAccessOf(options, cwd) {
+  const { localRefRoot, remoteRefHosts } = options;
+  return {
+    ...localRefRoot === void 0 ? {} : { localRoot: localRootOf(localRefRoot, cwd) },
+    ...remoteRefHosts === void 0 ? {} : { remoteHosts: remoteHostsOf(remoteRefHosts) }
+  };
+}
+
+export { refAccessOf };
+//# sourceMappingURL=ref-limit-options.mjs.map

package/dist/api/ref-limit-options.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-limit-options.mjs","sources":["../../src/api/ref-limit-options.ts"],"sourcesContent":["import path from \"node:path\";\nimport { fileURLToPath, pathToFileURL } from \"node:url\";\nimport type { RefAccess } from \"../application/ports/schema-loader.js\";\nimport { ERROR_CODES, OpenAPITypesafeError } from \"../domain/errors.js\";\nimport { hasUrlScheme } from \"../domain/location-text.js\";\nimport type { GeneratorOptions } from \"../types.js\";\n\n/**\n * The `$ref` limits of the options (threat model R1, R2, ADR-017), checked before anything loads.\n * A value of another type from JavaScript (`remoteRefHosts: \"a.com\"`, `localRefRoot: new\n * URL(\"https://…\")`) used to fail later as an error of the document.\n */\n\nconst FILE_PROTOCOL = \"file:\";\n\n/** What a value is, for the error; a URL is named by its protocol only, as it may hold secrets. */\nfunction kindOf(value: unknown): string {\n  if (value instanceof URL) {\n    return `a ${value.protocol} URL`;\n  }\n  if (Array.isArray(value)) {\n    return \"a list\";\n  }\n  return value === null ? \"null\" : `a ${typeof value}`;\n}\n\nfunction optionInvalid(option: string, expected: string, got: string): OpenAPITypesafeError {\n  return new OpenAPITypesafeError({\n    code: ERROR_CODES.OPTION_INVALID,\n    message: `The ${option} option must be ${expected}; got ${got}.`,\n    details: { option },\n  });\n}\n\nconst LOCAL_ROOT_EXPECTED = \"a directory path or a file: URL\";\n\n/**\n * A string as the CLI reads `--local-ref-root`: a URL when it has a scheme (`file:///specs/`),\n * else a path that resolves against the cwd. Undefined when it does not parse as a URL.\n */\nfunction localRootUrlOf(value: string, cwd: URL): URL | undefined {\n  if (!hasUrlScheme(value)) {\n    return pathToFileURL(path.resolve(fileURLToPath(cwd), value));\n  }\n  return URL.parse(value, cwd.href) ?? undefined;\n}\n\n/** The local root as a `file:` URL; the option is set, so it is not undefined. */\nfunction localRootOf(value: unknown, cwd: URL): URL {\n  const root = typeof value === \"string\" ? localRootUrlOf(value, cwd) : value;\n  if (root instanceof URL && root.protocol === FILE_PROTOCOL) {\n    return root;\n  }\n  const got = root === undefined ? \"a string that is no valid URL\" : kindOf(root);\n  throw optionInvalid(\"localRefRoot\", LOCAL_ROOT_EXPECTED, got);\n}\n\nfunction remoteHostsOf(value: unknown): readonly string[] {\n  if (!Array.isArray(value)) {\n    throw optionInvalid(\"remoteRefHosts\", \"a list of hosts\", kindOf(value));\n  }\n  const other = value.find((entry) => typeof entry !== \"string\");\n  if (other !== undefined) {\n    throw optionInvalid(\"remoteRefHosts\", \"a list of hosts\", `a list with ${kindOf(other)}`);\n  }\n  return value;\n}\n\n/** The limits of the options; fails with `OPTION_INVALID` for a value of another type. */\nexport function refAccessOf(options: GeneratorOptions, cwd: URL): RefAccess {\n  const { localRefRoot, remoteRefHosts } = options;\n  return {\n    ...(localRefRoot === undefined ? {} : { localRoot: localRootOf(localRefRoot, cwd) }),\n    ...(remoteRefHosts === undefined ? {} : { remoteHosts: remoteHostsOf(remoteRefHosts) }),\n  };\n}\n"],"names":[],"mappings":";;;;;AAaA,MAAM,aAAA,GAAgB,OAAA;AAGtB,SAAS,OAAO,KAAA,EAAwB;AACtC,EAAA,IAAI,iBAAiB,GAAA,EAAK;AACxB,IAAA,OAAO,CAAA,EAAA,EAAK,MAAM,QAAQ,CAAA,IAAA,CAAA;AAAA,EAC5B;AACA,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACxB,IAAA,OAAO,QAAA;AAAA,EACT;AACA,EAAA,OAAO,KAAA,KAAU,IAAA,GAAO,MAAA,GAAS,CAAA,EAAA,EAAK,OAAO,KAAK,CAAA,CAAA;AACpD;AAEA,SAAS,aAAA,CAAc,MAAA,EAAgB,QAAA,EAAkB,GAAA,EAAmC;AAC1F,EAAA,OAAO,IAAI,oBAAA,CAAqB;AAAA,IAC9B,MAAM,WAAA,CAAY,cAAA;AAAA,IAClB,SAAS,CAAA,IAAA,EAAO,MAAM,CAAA,gBAAA,EAAmB,QAAQ,SAAS,GAAG,CAAA,CAAA,CAAA;AAAA,IAC7D,OAAA,EAAS,EAAE,MAAA;AAAO,GACnB,CAAA;AACH;AAEA,MAAM,mBAAA,GAAsB,iCAAA;AAM5B,SAAS,cAAA,CAAe,OAAe,GAAA,EAA2B;AAChE,EAAA,IAAI,CAAC,YAAA,CAAa,KAAK,CAAA,EAAG;AACxB,IAAA,OAAO,cAAc,IAAA,CAAK,OAAA,CAAQ,cAAc,GAAG,CAAA,EAAG,KAAK,CAAC,CAAA;AAAA,EAC9D;AACA,EAAA,OAAO,GAAA,CAAI,KAAA,CAAM,KAAA,EAAO,GAAA,CAAI,IAAI,CAAA,IAAK,MAAA;AACvC;AAGA,SAAS,WAAA,CAAY,OAAgB,GAAA,EAAe;AAClD,EAAA,MAAM,OAAO,OAAO,KAAA,KAAU,WAAW,cAAA,CAAe,KAAA,EAAO,GAAG,CAAA,GAAI,KAAA;AACtE,EAAA,IAAI,IAAA,YAAgB,GAAA,IAAO,IAAA,CAAK,QAAA,KAAa,aAAA,EAAe;AAC1D,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,MAAM,GAAA,GAAM,IAAA,KAAS,MAAA,GAAY,+BAAA,GAAkC,OAAO,IAAI,CAAA;AAC9E,EAAA,MAAM,aAAA,CAAc,cAAA,EAAgB,mBAAA,EAAqB,GAAG,CAAA;AAC9D;AAEA,SAAS,cAAc,KAAA,EAAmC;AACxD,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACzB,IAAA,MAAM,aAAA,CAAc,gBAAA,EAAkB,iBAAA,EAAmB,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,EACxE;AACA,EAAA,MAAM,QAAQ,KAAA,CAAM,IAAA,CAAK,CAAC,KAAA,KAAU,OAAO,UAAU,QAAQ,CAAA;AAC7D,EAAA,IAAI,UAAU,MAAA,EAAW;AACvB,IAAA,MAAM,cAAc,gBAAA,EAAkB,iBAAA,EAAmB,eAAe,MAAA,CAAO,KAAK,CAAC,CAAA,CAAE,CAAA;AAAA,EACzF;AACA,EAAA,OAAO,KAAA;AACT;AAGO,SAAS,WAAA,CAAY,SAA2B,GAAA,EAAqB;AAC1E,EAAA,MAAM,EAAE,YAAA,EAAc,cAAA,EAAe,GAAI,OAAA;AACzC,EAAA,OAAO;AAAA,IACL,GAAI,YAAA,KAAiB,MAAA,GAAY,EAAC,GAAI,EAAE,SAAA,EAAW,WAAA,CAAY,YAAA,EAAc,GAAG,CAAA,EAAE;AAAA,IAClF,GAAI,mBAAmB,MAAA,GAAY,KAAK,EAAE,WAAA,EAAa,aAAA,CAAc,cAAc,CAAA;AAAE,GACvF;AACF;;"}

package/dist/api/schema-callbacks.cjs

@@ -5,58 +5,82 @@ const loadTypescript = require('../adapters/type-ast-bridge/load-typescript.cjs'
 const typescriptToIr = require('../adapters/type-ast-bridge/typescript-to-ir.cjs');
 const errors = require('../domain/errors.cjs');
 const constructors = require('../domain/ir/constructors.cjs');
+const irShape = require('../domain/ir/ir-shape.cjs');
 const legacyCallbackWarning = require('./legacy-callback-warning.cjs');
 const typeHelpers = require('./type-helpers.cjs');
 
+const LEGACY_PROPERTY_PROBLEM = "a property with syntax the generator cannot read";
 class UnreadablePropertyError extends errors.OpenAPITypesafeError {
-  constructor(path) {
+  constructor(path, problem = LEGACY_PROPERTY_PROBLEM) {
     super({
       code: errors.ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
-      message: `transformProperty at ${path} returned a property with syntax the generator cannot read`,
+      message: `transformProperty at ${path} returned ${problem}`,
       details: { callback: "transformProperty", path }
     });
     this.name = "UnreadablePropertyError";
   }
 }
 class UnreadableTypeError extends errors.OpenAPITypesafeError {
-  constructor(callback, path) {
+  constructor(callback, path, expected = "a TypeScript node") {
     super({
       code: errors.ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
-      message: `${callback} at ${path} returned a value that is not a TypeScript node`,
+      message: `${callback} at ${path} returned a value that is not ${expected}`,
       details: { callback, path }
     });
     this.name = "UnreadableTypeError";
   }
 }
+const IR_TYPE_EXPECTED = "an IR type or non-empty type text";
+const IR_PROPERTY_PROBLEM = "a value that is not an IR property the generator can print";
 function nodeOptions(ctx, location) {
   return { ...location, ctx };
 }
 function schemaCallbacks(ctx) {
   return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);
 }
-function fromCallbackType(type) {
-  return typeof type === "string" ? constructors.irRaw(type) : type;
+function fromCallbackType(callback, type, location) {
+  const candidate = typeof type === "string" ? constructors.irRaw(type) : type;
+  if (!irShape.isPrintableIrType(candidate)) {
+    throw new UnreadableTypeError(callback, location.path, IR_TYPE_EXPECTED);
+  }
+  return candidate;
 }
-function irCustomType(result) {
+function irCustomType(result, location) {
   if (result === void 0 || result === null) {
     return null;
   }
   if (typeof result === "object" && "schema" in result) {
-    return { type: fromCallbackType(result.schema), isOptional: Boolean(result.questionToken) };
+    const { schema, questionToken } = result;
+    return {
+      type: fromCallbackType("transform", schema, location),
+      isOptional: Boolean(questionToken)
+    };
+  }
+  return { type: fromCallbackType("transform", result, location), isOptional: false };
+}
+function irProperty(result, location) {
+  if (result === void 0 || result === null) {
+    return null;
+  }
+  if (!irShape.isPrintableIrProperty(result)) {
+    throw new UnreadablePropertyError(location.path, IR_PROPERTY_PROBLEM);
   }
-  return { type: fromCallbackType(result), isOptional: false };
+  return result;
 }
 function irSchemaCallbacks(ctx) {
   const transform = ctx.transform;
   const postTransform = ctx.postTransform;
   const transformProperty = ctx.transformProperty;
   return {
-    transform: (schema, location) => transform ? irCustomType(transform(schema, nodeOptions(ctx, location))) : null,
+    transform: (schema, location) => transform ? irCustomType(transform(schema, nodeOptions(ctx, location)), location) : null,
     postTransform(type, location) {
       const result = postTransform?.(type, nodeOptions(ctx, location));
-      return result === void 0 ? null : fromCallbackType(result);
+      return result === void 0 ? null : fromCallbackType("postTransform", result, location);
     },
-    transformProperty: (property, schema, location) => transformProperty?.(property, schema, nodeOptions(ctx, location)) ?? null
+    transformProperty: (property, schema, location) => transformProperty ? irProperty(
+      transformProperty(property, schema, nodeOptions(ctx, location)),
+      location
+    ) : null
   };
 }
 function readResultType(callback, result, location) {

package/dist/api/schema-callbacks.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"schema-callbacks.cjs","sources":["../../src/api/schema-callbacks.ts"],"sourcesContent":["import { toPropertySignature, toTypeNode } from \"../adapters/type-ast-bridge/ir-to-typescript.js\";\nimport { loadTypeScript } from \"../adapters/type-ast-bridge/load-typescript.js\";\nimport { fromPropertySignature } from \"../adapters/type-ast-bridge/typescript-to-ir.js\";\nimport type { ts } from \"../adapters/type-ast-bridge/typescript-types.js\";\nimport type {\n  CustomType,\n  SchemaCallbacks,\n  SchemaLocation,\n} from \"../application/transform/schema/schema-context.js\";\nimport { ERROR_CODES, OpenAPITypesafeError } from \"../domain/errors.js\";\nimport { irRaw } from \"../domain/ir/constructors.js\";\nimport type { IrPropertySignature, IrType } from \"../domain/ir/nodes.js\";\nimport type {\n  GlobalContext,\n  IrCallbackType,\n  IrPostTransform,\n  IrTransform,\n  IrTransformProperty,\n  LegacyCallbackOptions,\n  SchemaObject,\n  TransformNodeOptions,\n} from \"../types.js\";\nimport { warnLegacyCallback } from \"./legacy-callback-warning.js\";\nimport { toIrType } from \"./type-helpers.js\";\n\n/**\n * The user's schema callbacks as the transformers call them (ENGINEERING_PLAN 6.3, ADR-004).\n * With `irCallbacks: true` they receive and return IR; otherwise they receive TypeScript nodes and\n * their results are read by the bridge.\n */\n\nexport class UnreadablePropertyError extends OpenAPITypesafeError {\n  constructor(path: string | undefined) {\n    super({\n      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,\n      message:\n        `transformProperty at ${path} returned a property ` +\n        \"with syntax the generator cannot read\",\n      details: { callback: \"transformProperty\", path },\n    });\n    this.name = \"UnreadablePropertyError\";\n  }\n}\n\n/** A `transform` or `postTransform` result that is neither IR nor a TypeScript node. */\nexport class UnreadableTypeError extends OpenAPITypesafeError {\n  constructor(callback: \"transform\" | \"postTransform\", path: string | undefined) {\n    super({\n      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,\n      message: `${callback} at ${path} returned a value that is not a TypeScript node`,\n      details: { callback, path },\n    });\n    this.name = \"UnreadableTypeError\";\n  }\n}\n\nfunction nodeOptions(ctx: GlobalContext, location: SchemaLocation): TransformNodeOptions {\n  return { ...location, ctx } as TransformNodeOptions;\n}\n\n/** The callbacks of the run: IR callbacks when the run asks for them, legacy ones otherwise. */\nexport function schemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);\n}\n\n/** An IR callback type; text is a raw type, printed as written. */\nfunction fromCallbackType(type: IrCallbackType): IrType {\n  return typeof type === \"string\" ? irRaw(type) : type;\n}\n\nfunction irCustomType(result: ReturnType<IrTransform>): CustomType | null {\n  if (result === undefined || result === null) {\n    return null;\n  }\n  if (typeof result === \"object\" && \"schema\" in result) {\n    return { type: fromCallbackType(result.schema), isOptional: Boolean(result.questionToken) };\n  }\n  return { type: fromCallbackType(result), isOptional: false };\n}\n\n/**\n * The context fields hold either callback form; `irCallbacks` says which one, so the casts below\n * only name the form the user declared with `OpenAPITSIrOptions`.\n */\nfunction irSchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  const transform = ctx.transform as IrTransform | undefined;\n  const postTransform = ctx.postTransform as IrPostTransform | undefined;\n  const transformProperty = ctx.transformProperty as IrTransformProperty | undefined;\n  return {\n    transform: (schema, location) =>\n      transform\n        ? irCustomType(transform(schema as SchemaObject, nodeOptions(ctx, location)))\n        : null,\n    postTransform(type, location) {\n      const result = postTransform?.(type, nodeOptions(ctx, location));\n      return result === undefined ? null : fromCallbackType(result);\n    },\n    transformProperty: (property, schema, location) =>\n      transformProperty?.(property, schema as SchemaObject, nodeOptions(ctx, location)) ?? null,\n  };\n}\n\ntype LegacyTransform = NonNullable<LegacyCallbackOptions[\"transform\"]>;\ntype LegacyPostTransform = NonNullable<LegacyCallbackOptions[\"postTransform\"]>;\ntype LegacyTransformProperty = NonNullable<LegacyCallbackOptions[\"transformProperty\"]>;\n\n/** A legacy result type: IR from the helpers as it is; a TypeScript node through the bridge. */\n/**\n * IR nodes have a string `kind`, TypeScript nodes a number. JavaScript callers can return any\n * value, and anything else would crash the TypeScript printer later.\n */\nfunction readResultType(\n  callback: \"transform\" | \"postTransform\",\n  result: unknown,\n  location: SchemaLocation,\n): IrType {\n  const kind = (result as { kind?: unknown }).kind;\n  if (typeof kind !== \"string\" && typeof kind !== \"number\") {\n    throw new UnreadableTypeError(callback, location.path);\n  }\n  return toIrType(result as IrType | ts.TypeNode);\n}\n\nfunction legacyResultType(ctx: GlobalContext, type: unknown, location: SchemaLocation): IrType {\n  const result = readResultType(\"transform\", type, location);\n  if (typeof (type as { kind: unknown }).kind !== \"string\") {\n    warnLegacyCallback(ctx, \"transform\");\n  }\n  return result;\n}\n\nfunction legacyCustomType(\n  ctx: GlobalContext,\n  result: ReturnType<LegacyTransform>,\n  location: SchemaLocation,\n): CustomType | null {\n  if (!result || typeof result !== \"object\") {\n    return null;\n  }\n  if (\"schema\" in result) {\n    return {\n      type: legacyResultType(ctx, result.schema, location),\n      isOptional: Boolean(result.questionToken),\n    };\n  }\n  return { type: legacyResultType(ctx, result, location), isOptional: false };\n}\n\n/** See `irSchemaCallbacks` for the casts; `typeof` checks keep the original's tolerance. */\nfunction legacySchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  const transform = ctx.transform as LegacyTransform | undefined;\n  const postTransform = ctx.postTransform as LegacyPostTransform | undefined;\n  return {\n    transform: (schema, location) =>\n      typeof transform === \"function\"\n        ? legacyCustomType(\n            ctx,\n            transform(schema as SchemaObject, nodeOptions(ctx, location)),\n            location,\n          )\n        : null,\n    postTransform(type, location) {\n      if (typeof postTransform !== \"function\") {\n        return null;\n      }\n      warnLegacyCallback(ctx, \"postTransform\");\n      const result = postTransform(toTypeNode(loadTypeScript(), type), nodeOptions(ctx, location));\n      return result ? readResultType(\"postTransform\", result, location) : null;\n    },\n    transformProperty: (property, schema, location) =>\n      legacyTransformProperty(ctx, property, schema, location),\n  };\n}\n\nfunction isIrProperty(\n  property: IrPropertySignature | ts.PropertySignature,\n): property is IrPropertySignature {\n  return typeof property.kind === \"string\";\n}\n\nfunction legacyTransformProperty(\n  ctx: GlobalContext,\n  property: IrPropertySignature,\n  schema: unknown,\n  location: SchemaLocation,\n): IrPropertySignature | null {\n  const transformProperty = ctx.transformProperty as LegacyTransformProperty | undefined;\n  if (typeof transformProperty !== \"function\") {\n    return null;\n  }\n  warnLegacyCallback(ctx, \"transformProperty\");\n  const ts = loadTypeScript();\n  const options = nodeOptions(ctx, location);\n  const result = transformProperty(\n    toPropertySignature(ts, property),\n    schema as SchemaObject,\n    options,\n  );\n  if (!result) {\n    return null;\n  }\n  if (isIrProperty(result)) {\n    return result;\n  }\n  // JavaScript callers can return any value, so check the node kind before reading it.\n  const converted = ts.isPropertySignature(result) ? fromPropertySignature(ts, result) : null;\n  if (converted === null) {\n    throw new UnreadablePropertyError(location.path);\n  }\n  return converted;\n}\n"],"names":["OpenAPITypesafeError","ERROR_CODES","irRaw","toIrType","warnLegacyCallback","toTypeNode","loadTypeScript","toPropertySignature","fromPropertySignature"],"mappings":";;;;;;;;;;AA+BO,MAAM,gCAAgCA,2BAAA,CAAqB;AAAA,EAChE,YAAY,IAAA,EAA0B;AACpC,IAAA,KAAA,CAAM;AAAA,MACJ,MAAMC,kBAAA,CAAY,0BAAA;AAAA,MAClB,OAAA,EACE,wBAAwB,IAAI,CAAA,0DAAA,CAAA;AAAA,MAE9B,OAAA,EAAS,EAAE,QAAA,EAAU,mBAAA,EAAqB,IAAA;AAAK,KAChD,CAAA;AACD,IAAA,IAAA,CAAK,IAAA,GAAO,yBAAA;AAAA,EACd;AACF;AAGO,MAAM,4BAA4BD,2BAAA,CAAqB;AAAA,EAC5D,WAAA,CAAY,UAAyC,IAAA,EAA0B;AAC7E,IAAA,KAAA,CAAM;AAAA,MACJ,MAAMC,kBAAA,CAAY,0BAAA;AAAA,MAClB,OAAA,EAAS,CAAA,EAAG,QAAQ,CAAA,IAAA,EAAO,IAAI,CAAA,+CAAA,CAAA;AAAA,MAC/B,OAAA,EAAS,EAAE,QAAA,EAAU,IAAA;AAAK,KAC3B,CAAA;AACD,IAAA,IAAA,CAAK,IAAA,GAAO,qBAAA;AAAA,EACd;AACF;AAEA,SAAS,WAAA,CAAY,KAAoB,QAAA,EAAgD;AACvF,EAAA,OAAO,EAAE,GAAG,QAAA,EAAU,GAAA,EAAI;AAC5B;AAGO,SAAS,gBAAgB,GAAA,EAAqC;AACnE,EAAA,OAAO,IAAI,WAAA,GAAc,iBAAA,CAAkB,GAAG,CAAA,GAAI,sBAAsB,GAAG,CAAA;AAC7E;AAGA,SAAS,iBAAiB,IAAA,EAA8B;AACtD,EAAA,OAAO,OAAO,IAAA,KAAS,QAAA,GAAWC,kBAAA,CAAM,IAAI,CAAA,GAAI,IAAA;AAClD;AAEA,SAAS,aAAa,MAAA,EAAoD;AACxE,EAAA,IAAI,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,IAAA,EAAM;AAC3C,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,QAAA,IAAY,MAAA,EAAQ;AACpD,IAAA,OAAO,EAAE,IAAA,EAAM,gBAAA,CAAiB,MAAA,CAAO,MAAM,GAAG,UAAA,EAAY,OAAA,CAAQ,MAAA,CAAO,aAAa,CAAA,EAAE;AAAA,EAC5F;AACA,EAAA,OAAO,EAAE,IAAA,EAAM,gBAAA,CAAiB,MAAM,CAAA,EAAG,YAAY,KAAA,EAAM;AAC7D;AAMA,SAAS,kBAAkB,GAAA,EAAqC;AAC9D,EAAA,MAAM,YAAY,GAAA,CAAI,SAAA;AACtB,EAAA,MAAM,gBAAgB,GAAA,CAAI,aAAA;AAC1B,EAAA,MAAM,oBAAoB,GAAA,CAAI,iBAAA;AAC9B,EAAA,OAAO;AAAA,IACL,SAAA,EAAW,CAAC,MAAA,EAAQ,QAAA,KAClB,SAAA,GACI,YAAA,CAAa,SAAA,CAAU,MAAA,EAAwB,WAAA,CAAY,GAAA,EAAK,QAAQ,CAAC,CAAC,CAAA,GAC1E,IAAA;AAAA,IACN,aAAA,CAAc,MAAM,QAAA,EAAU;AAC5B,MAAA,MAAM,SAAS,aAAA,GAAgB,IAAA,EAAM,WAAA,CAAY,GAAA,EAAK,QAAQ,CAAC,CAAA;AAC/D,MAAA,OAAO,MAAA,KAAW,MAAA,GAAY,IAAA,GAAO,gBAAA,CAAiB,MAAM,CAAA;AAAA,IAC9D,CAAA;AAAA,IACA,iBAAA,EAAmB,CAAC,QAAA,EAAU,MAAA,EAAQ,QAAA,KACpC,iBAAA,GAAoB,QAAA,EAAU,MAAA,EAAwB,WAAA,CAAY,GAAA,EAAK,QAAQ,CAAC,CAAA,IAAK;AAAA,GACzF;AACF;AAWA,SAAS,cAAA,CACP,QAAA,EACA,MAAA,EACA,QAAA,EACQ;AACR,EAAA,MAAM,OAAQ,MAAA,CAA8B,IAAA;AAC5C,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,OAAO,SAAS,QAAA,EAAU;AACxD,IAAA,MAAM,IAAI,mBAAA,CAAoB,QAAA,EAAU,QAAA,CAAS,IAAI,CAAA;AAAA,EACvD;AACA,EAAA,OAAOC,qBAAS,MAA8B,CAAA;AAChD;AAEA,SAAS,gBAAA,CAAiB,GAAA,EAAoB,IAAA,EAAe,QAAA,EAAkC;AAC7F,EAAA,MAAM,MAAA,GAAS,cAAA,CAAe,WAAA,EAAa,IAAA,EAAM,QAAQ,CAAA;AACzD,EAAA,IAAI,OAAQ,IAAA,CAA2B,IAAA,KAAS,QAAA,EAAU;AACxD,IAAAC,wCAAA,CAAmB,KAAK,WAAW,CAAA;AAAA,EACrC;AACA,EAAA,OAAO,MAAA;AACT;AAEA,SAAS,gBAAA,CACP,GAAA,EACA,MAAA,EACA,QAAA,EACmB;AACnB,EAAA,IAAI,CAAC,MAAA,IAAU,OAAO,MAAA,KAAW,QAAA,EAAU;AACzC,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,IAAI,YAAY,MAAA,EAAQ;AACtB,IAAA,OAAO;AAAA,MACL,IAAA,EAAM,gBAAA,CAAiB,GAAA,EAAK,MAAA,CAAO,QAAQ,QAAQ,CAAA;AAAA,MACnD,UAAA,EAAY,OAAA,CAAQ,MAAA,CAAO,aAAa;AAAA,KAC1C;AAAA,EACF;AACA,EAAA,OAAO,EAAE,MAAM,gBAAA,CAAiB,GAAA,EAAK,QAAQ,QAAQ,CAAA,EAAG,YAAY,KAAA,EAAM;AAC5E;AAGA,SAAS,sBAAsB,GAAA,EAAqC;AAClE,EAAA,MAAM,YAAY,GAAA,CAAI,SAAA;AACtB,EAAA,MAAM,gBAAgB,GAAA,CAAI,aAAA;AAC1B,EAAA,OAAO;AAAA,IACL,WAAW,CAAC,MAAA,EAAQ,QAAA,KAClB,OAAO,cAAc,UAAA,GACjB,gBAAA;AAAA,MACE,GAAA;AAAA,MACA,SAAA,CAAU,MAAA,EAAwB,WAAA,CAAY,GAAA,EAAK,QAAQ,CAAC,CAAA;AAAA,MAC5D;AAAA,KACF,GACA,IAAA;AAAA,IACN,aAAA,CAAc,MAAM,QAAA,EAAU;AAC5B,MAAA,IAAI,OAAO,kBAAkB,UAAA,EAAY;AACvC,QAAA,OAAO,IAAA;AAAA,MACT;AACA,MAAAA,wCAAA,CAAmB,KAAK,eAAe,CAAA;AACvC,MAAA,MAAM,MAAA,GAAS,aAAA,CAAcC,yBAAA,CAAWC,6BAAA,EAAe,EAAG,IAAI,CAAA,EAAG,WAAA,CAAY,GAAA,EAAK,QAAQ,CAAC,CAAA;AAC3F,MAAA,OAAO,MAAA,GAAS,cAAA,CAAe,eAAA,EAAiB,MAAA,EAAQ,QAAQ,CAAA,GAAI,IAAA;AAAA,IACtE,CAAA;AAAA,IACA,iBAAA,EAAmB,CAAC,QAAA,EAAU,MAAA,EAAQ,aACpC,uBAAA,CAAwB,GAAA,EAAK,QAAA,EAAU,MAAA,EAAQ,QAAQ;AAAA,GAC3D;AACF;AAEA,SAAS,aACP,QAAA,EACiC;AACjC,EAAA,OAAO,OAAO,SAAS,IAAA,KAAS,QAAA;AAClC;AAEA,SAAS,uBAAA,CACP,GAAA,EACA,QAAA,EACA,MAAA,EACA,QAAA,EAC4B;AAC5B,EAAA,MAAM,oBAAoB,GAAA,CAAI,iBAAA;AAC9B,EAAA,IAAI,OAAO,sBAAsB,UAAA,EAAY;AAC3C,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAAF,wCAAA,CAAmB,KAAK,mBAAmB,CAAA;AAC3C,EAAA,MAAM,KAAKE,6BAAA,EAAe;AAC1B,EAAA,MAAM,OAAA,GAAU,WAAA,CAAY,GAAA,EAAK,QAAQ,CAAA;AACzC,EAAA,MAAM,MAAA,GAAS,iBAAA;AAAA,IACbC,kCAAA,CAAoB,IAAI,QAAQ,CAAA;AAAA,IAChC,MAAA;AAAA,IACA;AAAA,GACF;AACA,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,IAAI,YAAA,CAAa,MAAM,CAAA,EAAG;AACxB,IAAA,OAAO,MAAA;AAAA,EACT;AAEA,EAAA,MAAM,SAAA,GAAY,GAAG,mBAAA,CAAoB,MAAM,IAAIC,oCAAA,CAAsB,EAAA,EAAI,MAAM,CAAA,GAAI,IAAA;AACvF,EAAA,IAAI,cAAc,IAAA,EAAM;AACtB,IAAA,MAAM,IAAI,uBAAA,CAAwB,QAAA,CAAS,IAAI,CAAA;AAAA,EACjD;AACA,EAAA,OAAO,SAAA;AACT;;;;"}
+{"version":3,"file":"schema-callbacks.cjs","sources":["../../src/api/schema-callbacks.ts"],"sourcesContent":["import { toPropertySignature, toTypeNode } from \"../adapters/type-ast-bridge/ir-to-typescript.js\";\nimport { loadTypeScript } from \"../adapters/type-ast-bridge/load-typescript.js\";\nimport { fromPropertySignature } from \"../adapters/type-ast-bridge/typescript-to-ir.js\";\nimport type { ts } from \"../adapters/type-ast-bridge/typescript-types.js\";\nimport type {\n  CustomType,\n  SchemaCallbacks,\n  SchemaLocation,\n} from \"../application/transform/schema/schema-context.js\";\nimport { ERROR_CODES, OpenAPITypesafeError } from \"../domain/errors.js\";\nimport { irRaw } from \"../domain/ir/constructors.js\";\nimport { isPrintableIrProperty, isPrintableIrType } from \"../domain/ir/ir-shape.js\";\nimport type { IrPropertySignature, IrType } from \"../domain/ir/nodes.js\";\nimport type {\n  GlobalContext,\n  IrPostTransform,\n  IrTransform,\n  IrTransformProperty,\n  LegacyCallbackOptions,\n  SchemaObject,\n  TransformNodeOptions,\n} from \"../types.js\";\nimport { warnLegacyCallback } from \"./legacy-callback-warning.js\";\nimport { toIrType } from \"./type-helpers.js\";\n\n/**\n * The user's schema callbacks as the transformers call them (ENGINEERING_PLAN 6.3, ADR-004).\n * With `irCallbacks: true` they receive and return IR; otherwise they receive TypeScript nodes and\n * their results are read by the bridge.\n */\n\n/** What a legacy `transformProperty` result fails to be. */\nconst LEGACY_PROPERTY_PROBLEM = \"a property with syntax the generator cannot read\";\n\n/** A `transformProperty` result the generator cannot print as a property. */\nexport class UnreadablePropertyError extends OpenAPITypesafeError {\n  constructor(path: string | undefined, problem = LEGACY_PROPERTY_PROBLEM) {\n    super({\n      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,\n      message: `transformProperty at ${path} returned ${problem}`,\n      details: { callback: \"transformProperty\", path },\n    });\n    this.name = \"UnreadablePropertyError\";\n  }\n}\n\n/** A `transform` or `postTransform` result that is neither IR nor a TypeScript node. */\nexport class UnreadableTypeError extends OpenAPITypesafeError {\n  constructor(\n    callback: \"transform\" | \"postTransform\",\n    path: string | undefined,\n    expected = \"a TypeScript node\",\n  ) {\n    super({\n      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,\n      message: `${callback} at ${path} returned a value that is not ${expected}`,\n      details: { callback, path },\n    });\n    this.name = \"UnreadableTypeError\";\n  }\n}\n\n/** What an IR type result must be (docs/node.md, IR callbacks). */\nconst IR_TYPE_EXPECTED = \"an IR type or non-empty type text\";\n\n/** What an IR property result must be. */\nconst IR_PROPERTY_PROBLEM = \"a value that is not an IR property the generator can print\";\n\nfunction nodeOptions(ctx: GlobalContext, location: SchemaLocation): TransformNodeOptions {\n  return { ...location, ctx } as TransformNodeOptions;\n}\n\n/** The callbacks of the run: IR callbacks when the run asks for them, legacy ones otherwise. */\nexport function schemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);\n}\n\n/**\n * An IR callback type; text is a raw type, printed as written. Any other value, and IR the\n * printer cannot write as TypeScript, fails with `CALLBACK_RESULT_UNREADABLE` (`ir-shape.ts`).\n */\nfunction fromCallbackType(\n  callback: \"transform\" | \"postTransform\",\n  type: unknown,\n  location: SchemaLocation,\n): IrType {\n  const candidate = typeof type === \"string\" ? irRaw(type) : type;\n  if (!isPrintableIrType(candidate)) {\n    throw new UnreadableTypeError(callback, location.path, IR_TYPE_EXPECTED);\n  }\n  return candidate;\n}\n\nfunction irCustomType(result: unknown, location: SchemaLocation): CustomType | null {\n  if (result === undefined || result === null) {\n    return null;\n  }\n  if (typeof result === \"object\" && \"schema\" in result) {\n    const { schema, questionToken } = result as { schema: unknown; questionToken?: unknown };\n    return {\n      type: fromCallbackType(\"transform\", schema, location),\n      isOptional: Boolean(questionToken),\n    };\n  }\n  return { type: fromCallbackType(\"transform\", result, location), isOptional: false };\n}\n\nfunction irProperty(result: unknown, location: SchemaLocation): IrPropertySignature | null {\n  if (result === undefined || result === null) {\n    return null;\n  }\n  if (!isPrintableIrProperty(result)) {\n    throw new UnreadablePropertyError(location.path, IR_PROPERTY_PROBLEM);\n  }\n  return result;\n}\n\n/**\n * The context fields hold either callback form; `irCallbacks` says which one, so the casts below\n * only name the form the user declared with `OpenAPITSIrOptions`. The results are checked, since\n * JavaScript callers can return any value.\n */\nfunction irSchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  const transform = ctx.transform as IrTransform | undefined;\n  const postTransform = ctx.postTransform as IrPostTransform | undefined;\n  const transformProperty = ctx.transformProperty as IrTransformProperty | undefined;\n  return {\n    transform: (schema, location) =>\n      transform\n        ? irCustomType(transform(schema as SchemaObject, nodeOptions(ctx, location)), location)\n        : null,\n    postTransform(type, location) {\n      const result = postTransform?.(type, nodeOptions(ctx, location));\n      return result === undefined ? null : fromCallbackType(\"postTransform\", result, location);\n    },\n    transformProperty: (property, schema, location) =>\n      transformProperty\n        ? irProperty(\n            transformProperty(property, schema as SchemaObject, nodeOptions(ctx, location)),\n            location,\n          )\n        : null,\n  };\n}\n\ntype LegacyTransform = NonNullable<LegacyCallbackOptions[\"transform\"]>;\ntype LegacyPostTransform = NonNullable<LegacyCallbackOptions[\"postTransform\"]>;\ntype LegacyTransformProperty = NonNullable<LegacyCallbackOptions[\"transformProperty\"]>;\n\n/** A legacy result type: IR from the helpers as it is; a TypeScript node through the bridge. */\n/**\n * IR nodes have a string `kind`, TypeScript nodes a number. JavaScript callers can return any\n * value, and anything else would crash the TypeScript printer later.\n */\nfunction readResultType(\n  callback: \"transform\" | \"postTransform\",\n  result: unknown,\n  location: SchemaLocation,\n): IrType {\n  const kind = (result as { kind?: unknown }).kind;\n  if (typeof kind !== \"string\" && typeof kind !== \"number\") {\n    throw new UnreadableTypeError(callback, location.path);\n  }\n  return toIrType(result as IrType | ts.TypeNode);\n}\n\nfunction legacyResultType(ctx: GlobalContext, type: unknown, location: SchemaLocation): IrType {\n  const result = readResultType(\"transform\", type, location);\n  if (typeof (type as { kind: unknown }).kind !== \"string\") {\n    warnLegacyCallback(ctx, \"transform\");\n  }\n  return result;\n}\n\nfunction legacyCustomType(\n  ctx: GlobalContext,\n  result: ReturnType<LegacyTransform>,\n  location: SchemaLocation,\n): CustomType | null {\n  if (!result || typeof result !== \"object\") {\n    return null;\n  }\n  if (\"schema\" in result) {\n    return {\n      type: legacyResultType(ctx, result.schema, location),\n      isOptional: Boolean(result.questionToken),\n    };\n  }\n  return { type: legacyResultType(ctx, result, location), isOptional: false };\n}\n\n/** See `irSchemaCallbacks` for the casts; `typeof` checks keep the original's tolerance. */\nfunction legacySchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  const transform = ctx.transform as LegacyTransform | undefined;\n  const postTransform = ctx.postTransform as LegacyPostTransform | undefined;\n  return {\n    transform: (schema, location) =>\n      typeof transform === \"function\"\n        ? legacyCustomType(\n            ctx,\n            transform(schema as SchemaObject, nodeOptions(ctx, location)),\n            location,\n          )\n        : null,\n    postTransform(type, location) {\n      if (typeof postTransform !== \"function\") {\n        return null;\n      }\n      warnLegacyCallback(ctx, \"postTransform\");\n      const result = postTransform(toTypeNode(loadTypeScript(), type), nodeOptions(ctx, location));\n      return result ? readResultType(\"postTransform\", result, location) : null;\n    },\n    transformProperty: (property, schema, location) =>\n      legacyTransformProperty(ctx, property, schema, location),\n  };\n}\n\nfunction isIrProperty(\n  property: IrPropertySignature | ts.PropertySignature,\n): property is IrPropertySignature {\n  return typeof property.kind === \"string\";\n}\n\nfunction legacyTransformProperty(\n  ctx: GlobalContext,\n  property: IrPropertySignature,\n  schema: unknown,\n  location: SchemaLocation,\n): IrPropertySignature | null {\n  const transformProperty = ctx.transformProperty as LegacyTransformProperty | undefined;\n  if (typeof transformProperty !== \"function\") {\n    return null;\n  }\n  warnLegacyCallback(ctx, \"transformProperty\");\n  const ts = loadTypeScript();\n  const options = nodeOptions(ctx, location);\n  const result = transformProperty(\n    toPropertySignature(ts, property),\n    schema as SchemaObject,\n    options,\n  );\n  if (!result) {\n    return null;\n  }\n  if (isIrProperty(result)) {\n    return result;\n  }\n  // JavaScript callers can return any value, so check the node kind before reading it.\n  const converted = ts.isPropertySignature(result) ? fromPropertySignature(ts, result) : null;\n  if (converted === null) {\n    throw new UnreadablePropertyError(location.path);\n  }\n  return converted;\n}\n"],"names":["OpenAPITypesafeError","ERROR_CODES","irRaw","isPrintableIrType","isPrintableIrProperty","toIrType","warnLegacyCallback","toTypeNode","loadTypeScript","toPropertySignature","fromPropertySignature"],"mappings":"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"}

package/dist/api/schema-callbacks.mjs

@@ -3,58 +3,82 @@ import { loadTypeScript } from '../adapters/type-ast-bridge/load-typescript.mjs'
 import { fromPropertySignature } from '../adapters/type-ast-bridge/typescript-to-ir.mjs';
 import { OpenAPITypesafeError, ERROR_CODES } from '../domain/errors.mjs';
 import { irRaw } from '../domain/ir/constructors.mjs';
+import { isPrintableIrProperty, isPrintableIrType } from '../domain/ir/ir-shape.mjs';
 import { warnLegacyCallback } from './legacy-callback-warning.mjs';
 import { toIrType } from './type-helpers.mjs';
 
+const LEGACY_PROPERTY_PROBLEM = "a property with syntax the generator cannot read";
 class UnreadablePropertyError extends OpenAPITypesafeError {
-  constructor(path) {
+  constructor(path, problem = LEGACY_PROPERTY_PROBLEM) {
     super({
       code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
-      message: `transformProperty at ${path} returned a property with syntax the generator cannot read`,
+      message: `transformProperty at ${path} returned ${problem}`,
       details: { callback: "transformProperty", path }
     });
     this.name = "UnreadablePropertyError";
   }
 }
 class UnreadableTypeError extends OpenAPITypesafeError {
-  constructor(callback, path) {
+  constructor(callback, path, expected = "a TypeScript node") {
     super({
       code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,
-      message: `${callback} at ${path} returned a value that is not a TypeScript node`,
+      message: `${callback} at ${path} returned a value that is not ${expected}`,
       details: { callback, path }
     });
     this.name = "UnreadableTypeError";
   }
 }
+const IR_TYPE_EXPECTED = "an IR type or non-empty type text";
+const IR_PROPERTY_PROBLEM = "a value that is not an IR property the generator can print";
 function nodeOptions(ctx, location) {
   return { ...location, ctx };
 }
 function schemaCallbacks(ctx) {
   return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);
 }
-function fromCallbackType(type) {
-  return typeof type === "string" ? irRaw(type) : type;
+function fromCallbackType(callback, type, location) {
+  const candidate = typeof type === "string" ? irRaw(type) : type;
+  if (!isPrintableIrType(candidate)) {
+    throw new UnreadableTypeError(callback, location.path, IR_TYPE_EXPECTED);
+  }
+  return candidate;
 }
-function irCustomType(result) {
+function irCustomType(result, location) {
   if (result === void 0 || result === null) {
     return null;
   }
   if (typeof result === "object" && "schema" in result) {
-    return { type: fromCallbackType(result.schema), isOptional: Boolean(result.questionToken) };
+    const { schema, questionToken } = result;
+    return {
+      type: fromCallbackType("transform", schema, location),
+      isOptional: Boolean(questionToken)
+    };
+  }
+  return { type: fromCallbackType("transform", result, location), isOptional: false };
+}
+function irProperty(result, location) {
+  if (result === void 0 || result === null) {
+    return null;
+  }
+  if (!isPrintableIrProperty(result)) {
+    throw new UnreadablePropertyError(location.path, IR_PROPERTY_PROBLEM);
   }
-  return { type: fromCallbackType(result), isOptional: false };
+  return result;
 }
 function irSchemaCallbacks(ctx) {
   const transform = ctx.transform;
   const postTransform = ctx.postTransform;
   const transformProperty = ctx.transformProperty;
   return {
-    transform: (schema, location) => transform ? irCustomType(transform(schema, nodeOptions(ctx, location))) : null,
+    transform: (schema, location) => transform ? irCustomType(transform(schema, nodeOptions(ctx, location)), location) : null,
     postTransform(type, location) {
       const result = postTransform?.(type, nodeOptions(ctx, location));
-      return result === void 0 ? null : fromCallbackType(result);
+      return result === void 0 ? null : fromCallbackType("postTransform", result, location);
     },
-    transformProperty: (property, schema, location) => transformProperty?.(property, schema, nodeOptions(ctx, location)) ?? null
+    transformProperty: (property, schema, location) => transformProperty ? irProperty(
+      transformProperty(property, schema, nodeOptions(ctx, location)),
+      location
+    ) : null
   };
 }
 function readResultType(callback, result, location) {

package/dist/api/schema-callbacks.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"schema-callbacks.mjs","sources":["../../src/api/schema-callbacks.ts"],"sourcesContent":["import { toPropertySignature, toTypeNode } from \"../adapters/type-ast-bridge/ir-to-typescript.js\";\nimport { loadTypeScript } from \"../adapters/type-ast-bridge/load-typescript.js\";\nimport { fromPropertySignature } from \"../adapters/type-ast-bridge/typescript-to-ir.js\";\nimport type { ts } from \"../adapters/type-ast-bridge/typescript-types.js\";\nimport type {\n  CustomType,\n  SchemaCallbacks,\n  SchemaLocation,\n} from \"../application/transform/schema/schema-context.js\";\nimport { ERROR_CODES, OpenAPITypesafeError } from \"../domain/errors.js\";\nimport { irRaw } from \"../domain/ir/constructors.js\";\nimport type { IrPropertySignature, IrType } from \"../domain/ir/nodes.js\";\nimport type {\n  GlobalContext,\n  IrCallbackType,\n  IrPostTransform,\n  IrTransform,\n  IrTransformProperty,\n  LegacyCallbackOptions,\n  SchemaObject,\n  TransformNodeOptions,\n} from \"../types.js\";\nimport { warnLegacyCallback } from \"./legacy-callback-warning.js\";\nimport { toIrType } from \"./type-helpers.js\";\n\n/**\n * The user's schema callbacks as the transformers call them (ENGINEERING_PLAN 6.3, ADR-004).\n * With `irCallbacks: true` they receive and return IR; otherwise they receive TypeScript nodes and\n * their results are read by the bridge.\n */\n\nexport class UnreadablePropertyError extends OpenAPITypesafeError {\n  constructor(path: string | undefined) {\n    super({\n      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,\n      message:\n        `transformProperty at ${path} returned a property ` +\n        \"with syntax the generator cannot read\",\n      details: { callback: \"transformProperty\", path },\n    });\n    this.name = \"UnreadablePropertyError\";\n  }\n}\n\n/** A `transform` or `postTransform` result that is neither IR nor a TypeScript node. */\nexport class UnreadableTypeError extends OpenAPITypesafeError {\n  constructor(callback: \"transform\" | \"postTransform\", path: string | undefined) {\n    super({\n      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,\n      message: `${callback} at ${path} returned a value that is not a TypeScript node`,\n      details: { callback, path },\n    });\n    this.name = \"UnreadableTypeError\";\n  }\n}\n\nfunction nodeOptions(ctx: GlobalContext, location: SchemaLocation): TransformNodeOptions {\n  return { ...location, ctx } as TransformNodeOptions;\n}\n\n/** The callbacks of the run: IR callbacks when the run asks for them, legacy ones otherwise. */\nexport function schemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);\n}\n\n/** An IR callback type; text is a raw type, printed as written. */\nfunction fromCallbackType(type: IrCallbackType): IrType {\n  return typeof type === \"string\" ? irRaw(type) : type;\n}\n\nfunction irCustomType(result: ReturnType<IrTransform>): CustomType | null {\n  if (result === undefined || result === null) {\n    return null;\n  }\n  if (typeof result === \"object\" && \"schema\" in result) {\n    return { type: fromCallbackType(result.schema), isOptional: Boolean(result.questionToken) };\n  }\n  return { type: fromCallbackType(result), isOptional: false };\n}\n\n/**\n * The context fields hold either callback form; `irCallbacks` says which one, so the casts below\n * only name the form the user declared with `OpenAPITSIrOptions`.\n */\nfunction irSchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  const transform = ctx.transform as IrTransform | undefined;\n  const postTransform = ctx.postTransform as IrPostTransform | undefined;\n  const transformProperty = ctx.transformProperty as IrTransformProperty | undefined;\n  return {\n    transform: (schema, location) =>\n      transform\n        ? irCustomType(transform(schema as SchemaObject, nodeOptions(ctx, location)))\n        : null,\n    postTransform(type, location) {\n      const result = postTransform?.(type, nodeOptions(ctx, location));\n      return result === undefined ? null : fromCallbackType(result);\n    },\n    transformProperty: (property, schema, location) =>\n      transformProperty?.(property, schema as SchemaObject, nodeOptions(ctx, location)) ?? null,\n  };\n}\n\ntype LegacyTransform = NonNullable<LegacyCallbackOptions[\"transform\"]>;\ntype LegacyPostTransform = NonNullable<LegacyCallbackOptions[\"postTransform\"]>;\ntype LegacyTransformProperty = NonNullable<LegacyCallbackOptions[\"transformProperty\"]>;\n\n/** A legacy result type: IR from the helpers as it is; a TypeScript node through the bridge. */\n/**\n * IR nodes have a string `kind`, TypeScript nodes a number. JavaScript callers can return any\n * value, and anything else would crash the TypeScript printer later.\n */\nfunction readResultType(\n  callback: \"transform\" | \"postTransform\",\n  result: unknown,\n  location: SchemaLocation,\n): IrType {\n  const kind = (result as { kind?: unknown }).kind;\n  if (typeof kind !== \"string\" && typeof kind !== \"number\") {\n    throw new UnreadableTypeError(callback, location.path);\n  }\n  return toIrType(result as IrType | ts.TypeNode);\n}\n\nfunction legacyResultType(ctx: GlobalContext, type: unknown, location: SchemaLocation): IrType {\n  const result = readResultType(\"transform\", type, location);\n  if (typeof (type as { kind: unknown }).kind !== \"string\") {\n    warnLegacyCallback(ctx, \"transform\");\n  }\n  return result;\n}\n\nfunction legacyCustomType(\n  ctx: GlobalContext,\n  result: ReturnType<LegacyTransform>,\n  location: SchemaLocation,\n): CustomType | null {\n  if (!result || typeof result !== \"object\") {\n    return null;\n  }\n  if (\"schema\" in result) {\n    return {\n      type: legacyResultType(ctx, result.schema, location),\n      isOptional: Boolean(result.questionToken),\n    };\n  }\n  return { type: legacyResultType(ctx, result, location), isOptional: false };\n}\n\n/** See `irSchemaCallbacks` for the casts; `typeof` checks keep the original's tolerance. */\nfunction legacySchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  const transform = ctx.transform as LegacyTransform | undefined;\n  const postTransform = ctx.postTransform as LegacyPostTransform | undefined;\n  return {\n    transform: (schema, location) =>\n      typeof transform === \"function\"\n        ? legacyCustomType(\n            ctx,\n            transform(schema as SchemaObject, nodeOptions(ctx, location)),\n            location,\n          )\n        : null,\n    postTransform(type, location) {\n      if (typeof postTransform !== \"function\") {\n        return null;\n      }\n      warnLegacyCallback(ctx, \"postTransform\");\n      const result = postTransform(toTypeNode(loadTypeScript(), type), nodeOptions(ctx, location));\n      return result ? readResultType(\"postTransform\", result, location) : null;\n    },\n    transformProperty: (property, schema, location) =>\n      legacyTransformProperty(ctx, property, schema, location),\n  };\n}\n\nfunction isIrProperty(\n  property: IrPropertySignature | ts.PropertySignature,\n): property is IrPropertySignature {\n  return typeof property.kind === \"string\";\n}\n\nfunction legacyTransformProperty(\n  ctx: GlobalContext,\n  property: IrPropertySignature,\n  schema: unknown,\n  location: SchemaLocation,\n): IrPropertySignature | null {\n  const transformProperty = ctx.transformProperty as LegacyTransformProperty | undefined;\n  if (typeof transformProperty !== \"function\") {\n    return null;\n  }\n  warnLegacyCallback(ctx, \"transformProperty\");\n  const ts = loadTypeScript();\n  const options = nodeOptions(ctx, location);\n  const result = transformProperty(\n    toPropertySignature(ts, property),\n    schema as SchemaObject,\n    options,\n  );\n  if (!result) {\n    return null;\n  }\n  if (isIrProperty(result)) {\n    return result;\n  }\n  // JavaScript callers can return any value, so check the node kind before reading it.\n  const converted = ts.isPropertySignature(result) ? fromPropertySignature(ts, result) : null;\n  if (converted === null) {\n    throw new UnreadablePropertyError(location.path);\n  }\n  return converted;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema-callbacks.mjs","sources":["../../src/api/schema-callbacks.ts"],"sourcesContent":["import { toPropertySignature, toTypeNode } from \"../adapters/type-ast-bridge/ir-to-typescript.js\";\nimport { loadTypeScript } from \"../adapters/type-ast-bridge/load-typescript.js\";\nimport { fromPropertySignature } from \"../adapters/type-ast-bridge/typescript-to-ir.js\";\nimport type { ts } from \"../adapters/type-ast-bridge/typescript-types.js\";\nimport type {\n  CustomType,\n  SchemaCallbacks,\n  SchemaLocation,\n} from \"../application/transform/schema/schema-context.js\";\nimport { ERROR_CODES, OpenAPITypesafeError } from \"../domain/errors.js\";\nimport { irRaw } from \"../domain/ir/constructors.js\";\nimport { isPrintableIrProperty, isPrintableIrType } from \"../domain/ir/ir-shape.js\";\nimport type { IrPropertySignature, IrType } from \"../domain/ir/nodes.js\";\nimport type {\n  GlobalContext,\n  IrPostTransform,\n  IrTransform,\n  IrTransformProperty,\n  LegacyCallbackOptions,\n  SchemaObject,\n  TransformNodeOptions,\n} from \"../types.js\";\nimport { warnLegacyCallback } from \"./legacy-callback-warning.js\";\nimport { toIrType } from \"./type-helpers.js\";\n\n/**\n * The user's schema callbacks as the transformers call them (ENGINEERING_PLAN 6.3, ADR-004).\n * With `irCallbacks: true` they receive and return IR; otherwise they receive TypeScript nodes and\n * their results are read by the bridge.\n */\n\n/** What a legacy `transformProperty` result fails to be. */\nconst LEGACY_PROPERTY_PROBLEM = \"a property with syntax the generator cannot read\";\n\n/** A `transformProperty` result the generator cannot print as a property. */\nexport class UnreadablePropertyError extends OpenAPITypesafeError {\n  constructor(path: string | undefined, problem = LEGACY_PROPERTY_PROBLEM) {\n    super({\n      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,\n      message: `transformProperty at ${path} returned ${problem}`,\n      details: { callback: \"transformProperty\", path },\n    });\n    this.name = \"UnreadablePropertyError\";\n  }\n}\n\n/** A `transform` or `postTransform` result that is neither IR nor a TypeScript node. */\nexport class UnreadableTypeError extends OpenAPITypesafeError {\n  constructor(\n    callback: \"transform\" | \"postTransform\",\n    path: string | undefined,\n    expected = \"a TypeScript node\",\n  ) {\n    super({\n      code: ERROR_CODES.CALLBACK_RESULT_UNREADABLE,\n      message: `${callback} at ${path} returned a value that is not ${expected}`,\n      details: { callback, path },\n    });\n    this.name = \"UnreadableTypeError\";\n  }\n}\n\n/** What an IR type result must be (docs/node.md, IR callbacks). */\nconst IR_TYPE_EXPECTED = \"an IR type or non-empty type text\";\n\n/** What an IR property result must be. */\nconst IR_PROPERTY_PROBLEM = \"a value that is not an IR property the generator can print\";\n\nfunction nodeOptions(ctx: GlobalContext, location: SchemaLocation): TransformNodeOptions {\n  return { ...location, ctx } as TransformNodeOptions;\n}\n\n/** The callbacks of the run: IR callbacks when the run asks for them, legacy ones otherwise. */\nexport function schemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  return ctx.irCallbacks ? irSchemaCallbacks(ctx) : legacySchemaCallbacks(ctx);\n}\n\n/**\n * An IR callback type; text is a raw type, printed as written. Any other value, and IR the\n * printer cannot write as TypeScript, fails with `CALLBACK_RESULT_UNREADABLE` (`ir-shape.ts`).\n */\nfunction fromCallbackType(\n  callback: \"transform\" | \"postTransform\",\n  type: unknown,\n  location: SchemaLocation,\n): IrType {\n  const candidate = typeof type === \"string\" ? irRaw(type) : type;\n  if (!isPrintableIrType(candidate)) {\n    throw new UnreadableTypeError(callback, location.path, IR_TYPE_EXPECTED);\n  }\n  return candidate;\n}\n\nfunction irCustomType(result: unknown, location: SchemaLocation): CustomType | null {\n  if (result === undefined || result === null) {\n    return null;\n  }\n  if (typeof result === \"object\" && \"schema\" in result) {\n    const { schema, questionToken } = result as { schema: unknown; questionToken?: unknown };\n    return {\n      type: fromCallbackType(\"transform\", schema, location),\n      isOptional: Boolean(questionToken),\n    };\n  }\n  return { type: fromCallbackType(\"transform\", result, location), isOptional: false };\n}\n\nfunction irProperty(result: unknown, location: SchemaLocation): IrPropertySignature | null {\n  if (result === undefined || result === null) {\n    return null;\n  }\n  if (!isPrintableIrProperty(result)) {\n    throw new UnreadablePropertyError(location.path, IR_PROPERTY_PROBLEM);\n  }\n  return result;\n}\n\n/**\n * The context fields hold either callback form; `irCallbacks` says which one, so the casts below\n * only name the form the user declared with `OpenAPITSIrOptions`. The results are checked, since\n * JavaScript callers can return any value.\n */\nfunction irSchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  const transform = ctx.transform as IrTransform | undefined;\n  const postTransform = ctx.postTransform as IrPostTransform | undefined;\n  const transformProperty = ctx.transformProperty as IrTransformProperty | undefined;\n  return {\n    transform: (schema, location) =>\n      transform\n        ? irCustomType(transform(schema as SchemaObject, nodeOptions(ctx, location)), location)\n        : null,\n    postTransform(type, location) {\n      const result = postTransform?.(type, nodeOptions(ctx, location));\n      return result === undefined ? null : fromCallbackType(\"postTransform\", result, location);\n    },\n    transformProperty: (property, schema, location) =>\n      transformProperty\n        ? irProperty(\n            transformProperty(property, schema as SchemaObject, nodeOptions(ctx, location)),\n            location,\n          )\n        : null,\n  };\n}\n\ntype LegacyTransform = NonNullable<LegacyCallbackOptions[\"transform\"]>;\ntype LegacyPostTransform = NonNullable<LegacyCallbackOptions[\"postTransform\"]>;\ntype LegacyTransformProperty = NonNullable<LegacyCallbackOptions[\"transformProperty\"]>;\n\n/** A legacy result type: IR from the helpers as it is; a TypeScript node through the bridge. */\n/**\n * IR nodes have a string `kind`, TypeScript nodes a number. JavaScript callers can return any\n * value, and anything else would crash the TypeScript printer later.\n */\nfunction readResultType(\n  callback: \"transform\" | \"postTransform\",\n  result: unknown,\n  location: SchemaLocation,\n): IrType {\n  const kind = (result as { kind?: unknown }).kind;\n  if (typeof kind !== \"string\" && typeof kind !== \"number\") {\n    throw new UnreadableTypeError(callback, location.path);\n  }\n  return toIrType(result as IrType | ts.TypeNode);\n}\n\nfunction legacyResultType(ctx: GlobalContext, type: unknown, location: SchemaLocation): IrType {\n  const result = readResultType(\"transform\", type, location);\n  if (typeof (type as { kind: unknown }).kind !== \"string\") {\n    warnLegacyCallback(ctx, \"transform\");\n  }\n  return result;\n}\n\nfunction legacyCustomType(\n  ctx: GlobalContext,\n  result: ReturnType<LegacyTransform>,\n  location: SchemaLocation,\n): CustomType | null {\n  if (!result || typeof result !== \"object\") {\n    return null;\n  }\n  if (\"schema\" in result) {\n    return {\n      type: legacyResultType(ctx, result.schema, location),\n      isOptional: Boolean(result.questionToken),\n    };\n  }\n  return { type: legacyResultType(ctx, result, location), isOptional: false };\n}\n\n/** See `irSchemaCallbacks` for the casts; `typeof` checks keep the original's tolerance. */\nfunction legacySchemaCallbacks(ctx: GlobalContext): SchemaCallbacks {\n  const transform = ctx.transform as LegacyTransform | undefined;\n  const postTransform = ctx.postTransform as LegacyPostTransform | undefined;\n  return {\n    transform: (schema, location) =>\n      typeof transform === \"function\"\n        ? legacyCustomType(\n            ctx,\n            transform(schema as SchemaObject, nodeOptions(ctx, location)),\n            location,\n          )\n        : null,\n    postTransform(type, location) {\n      if (typeof postTransform !== \"function\") {\n        return null;\n      }\n      warnLegacyCallback(ctx, \"postTransform\");\n      const result = postTransform(toTypeNode(loadTypeScript(), type), nodeOptions(ctx, location));\n      return result ? readResultType(\"postTransform\", result, location) : null;\n    },\n    transformProperty: (property, schema, location) =>\n      legacyTransformProperty(ctx, property, schema, location),\n  };\n}\n\nfunction isIrProperty(\n  property: IrPropertySignature | ts.PropertySignature,\n): property is IrPropertySignature {\n  return typeof property.kind === \"string\";\n}\n\nfunction legacyTransformProperty(\n  ctx: GlobalContext,\n  property: IrPropertySignature,\n  schema: unknown,\n  location: SchemaLocation,\n): IrPropertySignature | null {\n  const transformProperty = ctx.transformProperty as LegacyTransformProperty | undefined;\n  if (typeof transformProperty !== \"function\") {\n    return null;\n  }\n  warnLegacyCallback(ctx, \"transformProperty\");\n  const ts = loadTypeScript();\n  const options = nodeOptions(ctx, location);\n  const result = transformProperty(\n    toPropertySignature(ts, property),\n    schema as SchemaObject,\n    options,\n  );\n  if (!result) {\n    return null;\n  }\n  if (isIrProperty(result)) {\n    return result;\n  }\n  // JavaScript callers can return any value, so check the node kind before reading it.\n  const converted = ts.isPropertySignature(result) ? fromPropertySignature(ts, result) : null;\n  if (converted === null) {\n    throw new UnreadablePropertyError(location.path);\n  }\n  return converted;\n}\n"],"names":[],"mappings":"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"}

package/dist/api/transform-context.cjs

@@ -2,6 +2,8 @@
 
 const changeCase = require('change-case');
 const documentFooter = require('../application/transform/footer/document-footer.cjs');
+const jsonPointer = require('../domain/openapi/json-pointer.cjs');
+const schemaDialect = require('../domain/openapi/schema-dialect.cjs');
 const defaultPorts = require('./default-ports.cjs');
 const footerSink = require('./footer-sink.cjs');
 const schemaCallbacks = require('./schema-callbacks.cjs');
@@ -37,6 +39,7 @@ function transformOptions(ctx) {
     immutable: ctx.immutable,
     propertiesRequiredByDefault: ctx.propertiesRequiredByDefault,
     readWriteMarkers: ctx.readWriteMarkers,
+    schemaDialect: ctx.schemaDialect ?? schemaDialect.SCHEMA_DIALECTS.OPENAPI_3_0,
     generatePathParams: ctx.generatePathParams,
     pathParamsAsTypes: ctx.pathParamsAsTypes,
     rootTypes: ctx.rootTypes,
@@ -64,9 +67,10 @@ function createTransformContext(ctx) {
     options: transformOptions(ctx),
     refs: { resolve: (ref) => ctx.resolve(ref) },
     discriminators: {
-      objectAt: (ref) => ctx.discriminators.objects[ref],
-      isHandled: (ref) => ctx.discriminators.refsHandled.includes(ref),
-      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[ref] ?? [],
+      // The scan keys pointers canonically; a caller may pass a `$ref` as the document writes it.
+      objectAt: (ref) => ctx.discriminators.objects[jsonPointer.canonicalRef(ref)],
+      isHandled: (ref) => ctx.discriminators.refsHandled.includes(jsonPointer.canonicalRef(ref)),
+      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[jsonPointer.canonicalRef(ref)] ?? [],
       enumParentOf: (schema) => ctx.discriminators.enumParents?.get(schema)
     },
     footer: runFooter(ctx),

package/dist/api/transform-context.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"transform-context.cjs","sources":["../../src/api/transform-context.ts"],"sourcesContent":["import * as changeCase from \"change-case\";\nimport { RunFooter } from \"../application/transform/footer/document-footer.js\";\nimport type {\n  DiscriminatorEnumParent,\n  SchemaLocation,\n} from \"../application/transform/schema/schema-context.js\";\nimport type {\n  DocumentFooter,\n  NameCasing,\n  TransformContext,\n  TransformDiagnostics,\n  TransformOptions,\n} from \"../application/transform/transform-context.js\";\nimport type { TransformNodeOptions } from \"../types.js\";\nimport { defaultLogger, monotonicNow } from \"./default-ports.js\";\nimport { ContextFooterSink } from \"./footer-sink.js\";\nimport type { RunContext } from \"./run-context.js\";\nimport { schemaCallbacks } from \"./schema-callbacks.js\";\n\n/**\n * Builds the ported transformers' context from the original `GlobalContext` (in a run, a\n * `RunContext`): options, refs, discriminators, the run footer and the user callbacks (see\n * `schema-callbacks.ts`).\n */\n\nfunction transformOptions(ctx: RunContext): TransformOptions {\n  return {\n    additionalProperties: ctx.additionalProperties,\n    alphabetize: ctx.alphabetize,\n    arrayLength: ctx.arrayLength,\n    binaryAsBlob: ctx.binaryAsBlob ?? false,\n    conditionalEnums: ctx.conditionalEnums,\n    dedupeEnums: ctx.dedupeEnums,\n    defaultNonNullable: ctx.defaultNonNullable,\n    emptyObjectsUnknown: ctx.emptyObjectsUnknown,\n    enum: ctx.enum,\n    enumValues: ctx.enumValues,\n    excludeDeprecated: ctx.excludeDeprecated,\n    fixes: new Set(ctx.fix ?? []),\n    immutable: ctx.immutable,\n    propertiesRequiredByDefault: ctx.propertiesRequiredByDefault,\n    readWriteMarkers: ctx.readWriteMarkers,\n    generatePathParams: ctx.generatePathParams,\n    pathParamsAsTypes: ctx.pathParamsAsTypes,\n    rootTypes: ctx.rootTypes,\n    rootTypesNoSchemaPrefix: ctx.rootTypesNoSchemaPrefix,\n    rootTypesKeepCasing: ctx.rootTypesKeepCasing,\n    exportType: ctx.exportType,\n    inject: ctx.inject,\n    makePathsEnum: ctx.makePathsEnum,\n  };\n}\n\n/** One footer per run: it holds the enum registry, so it lives on the run's context. */\nfunction runFooter(ctx: RunContext): DocumentFooter {\n  ctx.runFooter ??= new RunFooter(new ContextFooterSink(ctx.injectFooter), ctx.dedupeEnums);\n  return ctx.runFooter;\n}\n\nconst CASING: NameCasing = { pascalCase: (text) => changeCase.pascalCase(text) };\n\n/**\n * A monotonic clock and the run's logger (the default one for a user's own context), \"ts\" group.\n */\nfunction diagnostics(ctx: RunContext): TransformDiagnostics {\n  const logger = ctx.logger ?? defaultLogger(ctx.silent);\n  return {\n    now: monotonicNow,\n    debug: (message, durationMs) => logger.debug(message, \"ts\", durationMs),\n  };\n}\n\n/** The ported transformers' context for one call from a legacy transformer. */\nexport function createTransformContext(ctx: RunContext): TransformContext {\n  return {\n    options: transformOptions(ctx),\n    refs: { resolve: (ref) => ctx.resolve(ref) },\n    discriminators: {\n      objectAt: (ref) => ctx.discriminators.objects[ref],\n      isHandled: (ref) => ctx.discriminators.refsHandled.includes(ref),\n      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[ref] ?? [],\n      enumParentOf: (schema) =>\n        ctx.discriminators.enumParents?.get(schema) as DiscriminatorEnumParent | undefined,\n    },\n    footer: runFooter(ctx),\n    callbacks: schemaCallbacks(ctx),\n    diagnostics: diagnostics(ctx),\n    casing: CASING,\n  };\n}\n\n/** The transformer's location for the original options object. */\nexport function schemaLocation(options: TransformNodeOptions): SchemaLocation {\n  return { path: options.path, schema: options.schema };\n}\n"],"names":["RunFooter","ContextFooterSink","changeCase","defaultLogger","monotonicNow","schemaCallbacks"],"mappings":"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"}
+{"version":3,"file":"transform-context.cjs","sources":["../../src/api/transform-context.ts"],"sourcesContent":["import * as changeCase from \"change-case\";\nimport { RunFooter } from \"../application/transform/footer/document-footer.js\";\nimport type {\n  DiscriminatorEnumParent,\n  SchemaLocation,\n} from \"../application/transform/schema/schema-context.js\";\nimport type {\n  DocumentFooter,\n  NameCasing,\n  TransformContext,\n  TransformDiagnostics,\n  TransformOptions,\n} from \"../application/transform/transform-context.js\";\nimport { canonicalRef } from \"../domain/openapi/json-pointer.js\";\nimport { SCHEMA_DIALECTS } from \"../domain/openapi/schema-dialect.js\";\nimport type { TransformNodeOptions } from \"../types.js\";\nimport { defaultLogger, monotonicNow } from \"./default-ports.js\";\nimport { ContextFooterSink } from \"./footer-sink.js\";\nimport type { RunContext } from \"./run-context.js\";\nimport { schemaCallbacks } from \"./schema-callbacks.js\";\n\n/**\n * Builds the ported transformers' context from the original `GlobalContext` (in a run, a\n * `RunContext`): options, refs, discriminators, the run footer and the user callbacks (see\n * `schema-callbacks.ts`).\n */\n\nfunction transformOptions(ctx: RunContext): TransformOptions {\n  return {\n    additionalProperties: ctx.additionalProperties,\n    alphabetize: ctx.alphabetize,\n    arrayLength: ctx.arrayLength,\n    binaryAsBlob: ctx.binaryAsBlob ?? false,\n    conditionalEnums: ctx.conditionalEnums,\n    dedupeEnums: ctx.dedupeEnums,\n    defaultNonNullable: ctx.defaultNonNullable,\n    emptyObjectsUnknown: ctx.emptyObjectsUnknown,\n    enum: ctx.enum,\n    enumValues: ctx.enumValues,\n    excludeDeprecated: ctx.excludeDeprecated,\n    fixes: new Set(ctx.fix ?? []),\n    immutable: ctx.immutable,\n    propertiesRequiredByDefault: ctx.propertiesRequiredByDefault,\n    readWriteMarkers: ctx.readWriteMarkers,\n    schemaDialect: ctx.schemaDialect ?? SCHEMA_DIALECTS.OPENAPI_3_0,\n    generatePathParams: ctx.generatePathParams,\n    pathParamsAsTypes: ctx.pathParamsAsTypes,\n    rootTypes: ctx.rootTypes,\n    rootTypesNoSchemaPrefix: ctx.rootTypesNoSchemaPrefix,\n    rootTypesKeepCasing: ctx.rootTypesKeepCasing,\n    exportType: ctx.exportType,\n    inject: ctx.inject,\n    makePathsEnum: ctx.makePathsEnum,\n  };\n}\n\n/** One footer per run: it holds the enum registry, so it lives on the run's context. */\nfunction runFooter(ctx: RunContext): DocumentFooter {\n  ctx.runFooter ??= new RunFooter(new ContextFooterSink(ctx.injectFooter), ctx.dedupeEnums);\n  return ctx.runFooter;\n}\n\nconst CASING: NameCasing = { pascalCase: (text) => changeCase.pascalCase(text) };\n\n/**\n * A monotonic clock and the run's logger (the default one for a user's own context), \"ts\" group.\n */\nfunction diagnostics(ctx: RunContext): TransformDiagnostics {\n  const logger = ctx.logger ?? defaultLogger(ctx.silent);\n  return {\n    now: monotonicNow,\n    debug: (message, durationMs) => logger.debug(message, \"ts\", durationMs),\n  };\n}\n\n/** The ported transformers' context for one call from a legacy transformer. */\nexport function createTransformContext(ctx: RunContext): TransformContext {\n  return {\n    options: transformOptions(ctx),\n    refs: { resolve: (ref) => ctx.resolve(ref) },\n    discriminators: {\n      // The scan keys pointers canonically; a caller may pass a `$ref` as the document writes it.\n      objectAt: (ref) => ctx.discriminators.objects[canonicalRef(ref)],\n      isHandled: (ref) => ctx.discriminators.refsHandled.includes(canonicalRef(ref)),\n      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[canonicalRef(ref)] ?? [],\n      enumParentOf: (schema) =>\n        ctx.discriminators.enumParents?.get(schema) as DiscriminatorEnumParent | undefined,\n    },\n    footer: runFooter(ctx),\n    callbacks: schemaCallbacks(ctx),\n    diagnostics: diagnostics(ctx),\n    casing: CASING,\n  };\n}\n\n/** The transformer's location for the original options object. */\nexport function schemaLocation(options: TransformNodeOptions): SchemaLocation {\n  return { path: options.path, schema: options.schema };\n}\n"],"names":["SCHEMA_DIALECTS","RunFooter","ContextFooterSink","changeCase","defaultLogger","monotonicNow","canonicalRef","schemaCallbacks"],"mappings":"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"}

package/dist/api/transform-context.mjs

@@ -1,5 +1,7 @@
 import * as changeCase from 'change-case';
 import { RunFooter } from '../application/transform/footer/document-footer.mjs';
+import { canonicalRef } from '../domain/openapi/json-pointer.mjs';
+import { SCHEMA_DIALECTS } from '../domain/openapi/schema-dialect.mjs';
 import { defaultLogger, monotonicNow } from './default-ports.mjs';
 import { ContextFooterSink } from './footer-sink.mjs';
 import { schemaCallbacks } from './schema-callbacks.mjs';
@@ -21,6 +23,7 @@ function transformOptions(ctx) {
     immutable: ctx.immutable,
     propertiesRequiredByDefault: ctx.propertiesRequiredByDefault,
     readWriteMarkers: ctx.readWriteMarkers,
+    schemaDialect: ctx.schemaDialect ?? SCHEMA_DIALECTS.OPENAPI_3_0,
     generatePathParams: ctx.generatePathParams,
     pathParamsAsTypes: ctx.pathParamsAsTypes,
     rootTypes: ctx.rootTypes,
@@ -48,9 +51,10 @@ function createTransformContext(ctx) {
     options: transformOptions(ctx),
     refs: { resolve: (ref) => ctx.resolve(ref) },
     discriminators: {
-      objectAt: (ref) => ctx.discriminators.objects[ref],
-      isHandled: (ref) => ctx.discriminators.refsHandled.includes(ref),
-      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[ref] ?? [],
+      // The scan keys pointers canonically; a caller may pass a `$ref` as the document writes it.
+      objectAt: (ref) => ctx.discriminators.objects[canonicalRef(ref)],
+      isHandled: (ref) => ctx.discriminators.refsHandled.includes(canonicalRef(ref)),
+      otherPropertiesAt: (ref) => ctx.discriminators.otherProperties?.[canonicalRef(ref)] ?? [],
       enumParentOf: (schema) => ctx.discriminators.enumParents?.get(schema)
     },
     footer: runFooter(ctx),