@rawan-temo/prisma-zod-generator 3.3.1-config-coercion.0

package/src/typed-json/annotation-parser.ts

@@ -0,0 +1,252 @@
+/**
+ * Parser for prisma-json-types-generator (PJTG) field annotations.
+ *
+ * PJTG carries two forms in a Prisma triple-slash comment:
+ *
+ *   /// [TypeName]       a reference to `<namespace>.TypeName`
+ *   /// ![<ts type>]     an inline TypeScript type
+ *
+ * This module only *recognises* them. It converts nothing and emits nothing;
+ * see `ts-type-to-zod.ts` for conversion and `resolver.ts` for the public API.
+ *
+ * The recognition rules are deliberately strict. A false positive here means a
+ * generated schema built from prose, which would reject valid production data
+ * at runtime. A false negative only means today's untyped behaviour is kept.
+ * So an annotation must own its line: leading and trailing whitespace is fine,
+ * anything else is not. That rejects markdown links `[text](url)`, markdown
+ * images `![alt](url)`, prose in brackets, and unbalanced brackets.
+ */
+
+/** Which of PJTG's two forms was found. */
+export type PjtgAnnotationKind = 'namespace-ref' | 'inline-type';
+
+export interface PjtgAnnotation {
+  kind: PjtgAnnotationKind;
+  /**
+   * For `namespace-ref`, the bare type name (`WorkflowNode`).
+   * For `inline-type`, the TypeScript type text with the outer `![` `]` removed.
+   */
+  value: string;
+  /** The annotation exactly as it appeared, e.g. `[WorkflowNode]` or `![1 | 2]`. */
+  raw: string;
+  /** Zero-based index of the documentation line the annotation starts on. */
+  line: number;
+}
+
+export interface PjtgAnnotationParseResult {
+  /** The single annotation found, or null when there is none or more than one. */
+  annotation: PjtgAnnotation | null;
+  /** True when the documentation carries any `@zod.` annotation. */
+  hasZodAnnotations: boolean;
+  /** True when `@zod...custom.use(...)` is present, which replaces the base schema and wins. */
+  hasZodCustomUse: boolean;
+  /** True when `@zod.custom({ ... })` is present, which also replaces the base schema. */
+  hasZodCustom: boolean;
+  /** Non-fatal diagnostics worth surfacing to the user. */
+  warnings: string[];
+  /** The documentation with every recognised annotation line removed. */
+  strippedDocumentation: string;
+}
+
+/** A JavaScript/TypeScript identifier, which is all `[TypeName]` may contain. */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+const ZOD_ANNOTATION = /@zod\s*\./i;
+const ZOD_MARKER = /@zod\b/i;
+const ZOD_CUSTOM_USE = /\.\s*custom\s*\.\s*use\s*\(/;
+const ZOD_CUSTOM_OBJECT = /@zod\s*\.\s*custom\s*\(/i;
+
+const EMPTY_RESULT: PjtgAnnotationParseResult = Object.freeze({
+  annotation: null,
+  hasZodAnnotations: false,
+  hasZodCustomUse: false,
+  hasZodCustom: false,
+  warnings: Object.freeze([]) as unknown as string[],
+  strippedDocumentation: '',
+});
+
+/**
+ * Find the index of the bracket closing the one at `open`.
+ *
+ * Nesting of `[]`, `{}` and `()` is tracked, and string literals are skipped
+ * wholesale so that a bracket or quote inside `'a|b'` cannot unbalance the scan.
+ * Returns -1 when the brackets do not balance or a closer arrives out of order.
+ */
+function findMatchingBracket(text: string, open: number): number {
+  const stack: string[] = [];
+  for (let i = open; i < text.length; i++) {
+    const char = text[i];
+
+    if (char === "'" || char === '"' || char === '`') {
+      const end = skipStringLiteral(text, i);
+      if (end < 0) return -1;
+      i = end;
+      continue;
+    }
+
+    if (char === '[' || char === '{' || char === '(') {
+      stack.push(char);
+      continue;
+    }
+
+    if (char === ']' || char === '}' || char === ')') {
+      const expected = char === ']' ? '[' : char === '}' ? '{' : '(';
+      if (stack[stack.length - 1] !== expected) return -1;
+      stack.pop();
+      if (stack.length === 0) return i;
+    }
+  }
+  return -1;
+}
+
+/** Index of the closing quote for the literal starting at `start`, or -1 if unterminated. */
+function skipStringLiteral(text: string, start: number): number {
+  const quote = text[start];
+  for (let i = start + 1; i < text.length; i++) {
+    const char = text[i];
+    if (char === '\\') {
+      i++;
+      continue;
+    }
+    if (char === quote) return i;
+  }
+  return -1;
+}
+
+interface Candidate {
+  annotation: PjtgAnnotation;
+  /** Zero-based index of the last documentation line the annotation occupies. */
+  endLine: number;
+}
+
+/**
+ * Parse a field's `documentation` for a PJTG annotation.
+ *
+ * Never throws. When the documentation is ambiguous (two different annotations)
+ * the result carries a warning and no annotation, so the caller falls back to
+ * today's behaviour rather than picking one.
+ */
+export function parsePjtgAnnotation(
+  documentation: string | undefined | null,
+): PjtgAnnotationParseResult {
+  if (!documentation || documentation.trim() === '') {
+    return { ...EMPTY_RESULT, warnings: [] };
+  }
+
+  const text = documentation.replace(/\r\n/g, '\n');
+  const lines = text.split('\n');
+  const warnings: string[] = [];
+  const candidates: Candidate[] = [];
+  const annotationLines = new Set<number>();
+
+  // Offset of the first character of each line, so bracket matching can run
+  // across the whole text while candidates are still anchored to line starts.
+  const lineStarts: number[] = [];
+  let offset = 0;
+  for (const line of lines) {
+    lineStarts.push(offset);
+    offset += line.length + 1;
+  }
+
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const line = lines[lineIndex];
+    const leading = line.length - line.trimStart().length;
+    const start = lineStarts[lineIndex] + leading;
+
+    const bang = text[start] === '!' && text[start + 1] === '[';
+    const openIndex = bang ? start + 1 : start;
+    if (text[openIndex] !== '[') continue;
+
+    const closeIndex = findMatchingBracket(text, openIndex);
+    if (closeIndex < 0) {
+      // Only complain about the `![` form. A stray `[` is far more likely to be
+      // prose, and warning on prose trains people to ignore warnings.
+      if (bang) {
+        warnings.push(
+          `Ignoring what looks like a PJTG annotation on line ${lineIndex + 1}: unbalanced brackets in "${line.trim()}".`,
+        );
+      }
+      continue;
+    }
+
+    // The annotation must run to the end of its line. This is what rejects
+    // markdown links `[text](url)` and markdown images `![alt](url)`, both of
+    // which balance perfectly but are followed by a parenthesised group.
+    const endLine = lineIndexOf(lineStarts, closeIndex);
+    const tail = text.slice(closeIndex + 1, lineStarts[endLine] + lines[endLine].length);
+    if (tail.trim() !== '') continue;
+
+    const raw = text.slice(start, closeIndex + 1);
+    const inner = text.slice(openIndex + 1, closeIndex).trim();
+
+    if (bang) {
+      if (inner === '') {
+        warnings.push(
+          `Ignoring an empty PJTG annotation "![]" on line ${lineIndex + 1}: there is no type to convert.`,
+        );
+        continue;
+      }
+      candidates.push({
+        annotation: { kind: 'inline-type', value: inner, raw, line: lineIndex },
+        endLine,
+      });
+    } else {
+      // `[anything that is not a bare identifier]` is prose, not an annotation.
+      if (!IDENTIFIER.test(inner)) continue;
+      candidates.push({
+        annotation: { kind: 'namespace-ref', value: inner, raw, line: lineIndex },
+        endLine,
+      });
+    }
+
+    for (let i = lineIndex; i <= endLine; i++) annotationLines.add(i);
+    lineIndex = endLine;
+  }
+
+  const distinct = new Set(candidates.map((c) => `${c.annotation.kind}:${c.annotation.value}`));
+  let annotation: PjtgAnnotation | null = null;
+  if (distinct.size === 1) {
+    annotation = candidates[0].annotation;
+  } else if (distinct.size > 1) {
+    warnings.push(
+      `Ignoring PJTG annotations: found more than one on the same field (${candidates
+        .map((c) => c.annotation.raw)
+        .join(
+          ', ',
+        )}). Remove all but one; guessing which was meant risks generating the wrong schema.`,
+    );
+  }
+
+  const strippedDocumentation = lines
+    .filter((_, index) => !annotationLines.has(index))
+    .join('\n')
+    .trim();
+
+  return {
+    annotation,
+    hasZodAnnotations: ZOD_ANNOTATION.test(text),
+    hasZodCustomUse: ZOD_MARKER.test(text) && ZOD_CUSTOM_USE.test(text),
+    hasZodCustom: ZOD_CUSTOM_OBJECT.test(text),
+    warnings,
+    strippedDocumentation,
+  };
+}
+
+/** Zero-based line index containing `offset`. */
+function lineIndexOf(lineStarts: number[], offset: number): number {
+  let index = 0;
+  while (index + 1 < lineStarts.length && lineStarts[index + 1] <= offset) index++;
+  return index;
+}
+
+/**
+ * Cheap yes/no for whether a field carries a PJTG annotation.
+ *
+ * Always agrees with `parsePjtgAnnotation(...).annotation !== null`.
+ */
+export function detectPjtgAnnotation(documentation: string | undefined | null): boolean {
+  if (!documentation) return false;
+  // Fast reject: an annotation always begins a line with `[` or `![`.
+  if (!/(^|\n)[^\S\n]*!?\[/.test(documentation.replace(/\r\n/g, '\n'))) return false;
+  return parsePjtgAnnotation(documentation).annotation !== null;
+}

package/src/typed-json/emission.ts

@@ -0,0 +1,239 @@
+/**
+ * The parts of typed-JSON wiring that both emitters need.
+ *
+ * `src/typed-json/resolver.ts` answers "what schema does this field get?" and knows
+ * nothing about files. This module covers the two things that only make sense once an
+ * emitter is writing a file: which imports that file actually needs, and how to report a
+ * diagnostic without repeating it once per generated schema.
+ */
+
+import type { CustomImport } from '../parsers/zod-comments';
+import { logger } from '../utils/logger';
+import type { TypedJsonResult } from './resolver';
+
+/** Prisma scalar input types a PJTG annotation may replace. */
+const TYPED_JSON_INPUT_TYPES = new Set(['Json', 'String', 'Int', 'Float']);
+
+/**
+ * The members of a `<Model><Create|Update><field>Input` list wrapper that hold values of
+ * the wrapped column, and so inherit its annotation.
+ *
+ * `{ set: [...] }` and `{ push: ... }` are how a list column is written through Prisma,
+ * which is the whole reason these wrappers need typing. The list is closed rather than
+ * "everything in the file" so that any member Prisma adds later is left alone until
+ * somebody has checked that a replacement is right for it.
+ */
+export const LIST_OPERATION_MEMBERS = new Set(['set', 'push']);
+
+/**
+ * Prisma's shared per-scalar update-operations input: `StringFieldUpdateOperationsInput`,
+ * `NullableIntFieldUpdateOperationsInput`, and so on.
+ *
+ * One of these exists per scalar type for the whole schema, not per column, which is why
+ * it can never carry one column's annotation.
+ */
+const SHARED_FIELD_UPDATE_OPERATIONS_INPUT =
+  /^(?:Nullable)?[A-Za-z0-9]+FieldUpdateOperationsInput$/;
+
+export function isSharedFieldUpdateOperationsInput(name: unknown): boolean {
+  return typeof name === 'string' && SHARED_FIELD_UPDATE_OPERATIONS_INPUT.test(name);
+}
+
+/**
+ * The name of the per-field copy of a shared update-operations input.
+ *
+ * `Post.label` gets `PostLabelFieldUpdateOperationsInput`. The name is not guaranteed
+ * unique on its own - `Post.labelField` and `PostLabel.field` both produce
+ * `PostLabelFieldFieldUpdateOperationsInput` - so the caller checks for a clash and
+ * leaves the field alone when it finds one.
+ */
+export function typedFieldUpdateOperationsName(modelName: string, fieldName: string): string {
+  const head = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
+  return `${modelName}${head}FieldUpdateOperationsInput`;
+}
+
+/**
+ * Whether an annotation is allowed to replace this input type.
+ *
+ * Deliberately a short allow-list rather than "every scalar". These are the types the
+ * upstream corpus annotates, and a type absent from it is one where nobody has checked
+ * that a replacement composes with the rest of the pipeline. Widening it later is cheap;
+ * shipping a wrong schema for `Bytes` is not.
+ */
+export function isTypedJsonInputType(inputType: unknown): boolean {
+  return typeof inputType === 'string' && TYPED_JSON_INPUT_TYPES.has(inputType);
+}
+
+/**
+ * Schema names that must never receive a typed replacement, even though their members are
+ * named after model fields.
+ *
+ * `*ScalarWhereWithAggregatesInput` is the one that is easy to get wrong. Its inline
+ * scalar branch looks exactly like `WhereInput`'s, but upstream requires it to stay
+ * untyped: `{ price: { gt: 100 } }` has to keep typechecking there without a cast, since
+ * an aggregate comparison is over the whole group and not over one annotated value.
+ *
+ * `*Select` and the `*AggregateInput` family are boolean-flag schemas whose members happen
+ * to share the field names; the existing `extractZodValidationsForField` bails on exactly
+ * these two for the same reason.
+ *
+ * Every test here is a whole-name match, never a substring. Prisma builds these names as
+ * `<Model><suffix>`, and a model name is arbitrary user text: `includes('Select')` reads
+ * `SelectionRoundCreateInput` as a flag schema and silently drops typing from every
+ * `objects/` schema of a model called `SelectionRound`, while its `models/` and `results/`
+ * schemas keep it. The two boolean-flag families this skips - `<Model>Select`,
+ * `<CountOutputType>Select`, `<Model><Count|Min|Max|Sum|Avg>AggregateInput` - are all
+ * suffixes, so matching the suffix loses none of them.
+ */
+export function isTypedJsonExcludedSchema(schemaName: string | undefined | null): boolean {
+  if (!schemaName) return false;
+  if (/^\w+Select$/.test(schemaName)) return true;
+  if (/^\w+ScalarWhereWithAggregatesInput$/.test(schemaName)) return true;
+  if (/^\w+(?:Count|Min|Max|Sum|Avg)AggregateInput$/.test(schemaName)) return true;
+  return false;
+}
+
+/**
+ * The token the general model-name patterns swallow.
+ *
+ * `<Model>UncheckedCreateWithout<Relation>Input` also reads as a `CreateWithout` of a model
+ * called `<Model>Unchecked`, and `\w+` is greedy, so the earlier pattern wins.
+ */
+const UNCHECKED_SUFFIX = 'Unchecked';
+
+/**
+ * The model whose fields an input-object schema's members refer to, repaired for the one
+ * shape the general extraction reads wrong.
+ *
+ * `Transformer.extractModelNameFromContext` tries `<Model>CreateWithout<Relation>Input`
+ * before `<Model>UncheckedCreateWithout<Relation>Input`, so it answers `WorkflowUnchecked`
+ * for `WorkflowUncheckedCreateWithoutPostsInput` - a model that does not exist, so the
+ * annotation lookup finds nothing and the field is emitted untyped. That is not a cosmetic
+ * gap: a nested write offers `z.union([Checked, Unchecked])`, so the untyped half is a way
+ * round the typed half and the annotation stops constraining anything at all.
+ *
+ * The repair is deliberately a repair and not a rewrite of the extraction. That function
+ * also drives file naming and field filtering, where a changed answer moves bytes for
+ * people who have never configured `typedJson`. So this takes the extraction's answer as
+ * given, accepts it when it names a real model, and otherwise strips only a trailing
+ * `Unchecked`. Anything else stays unresolved, which is the same "leave the field alone"
+ * that an unknown model name already produced.
+ *
+ * The exact match is tried first, so a model genuinely called `FooUnchecked` still wins
+ * over `Foo` plus the token.
+ */
+export function resolveTypedJsonOwnerModel(
+  extractedName: string | undefined | null,
+  isKnownModel: (name: string) => boolean,
+): string | null {
+  if (!extractedName) return null;
+  if (isKnownModel(extractedName)) return extractedName;
+  if (!extractedName.endsWith(UNCHECKED_SUFFIX)) return null;
+
+  const owner = extractedName.slice(0, -UNCHECKED_SUFFIX.length);
+  return owner && isKnownModel(owner) ? owner : null;
+}
+
+/**
+ * Keep only the imports whose names the emitted body actually uses, then collapse them to
+ * one statement per module.
+ *
+ * Both steps matter and the order matters. The resolver builds imports per field, so a
+ * model with three annotated fields yields three statements from the same module; merging
+ * makes that one. Filtering first means the merged statement names only what this
+ * particular file references, so `WorkflowWhereInput` (which types scalar branches but not
+ * Json ones) does not end up importing a schema it never mentions.
+ *
+ * Names are sorted so the emitted bytes do not depend on field order in the schema.
+ */
+export function mergeTypedJsonImports(
+  imports: CustomImport[],
+  schemaBody: string,
+  /**
+   * Emit one statement per imported name instead of one per module.
+   *
+   * For single-file mode, where every schema's imports are concatenated into one bundle and
+   * de-duplicated by exact statement text. Merged statements differ from file to file
+   * (`{ A }` here, `{ A, B, C }` there), so text de-duplication keeps both and the bundle
+   * imports `A` twice - a duplicate-identifier error. One name per statement makes every
+   * occurrence of a name byte-identical, so it collapses to exactly one.
+   */
+  oneNamePerStatement = false,
+): CustomImport[] {
+  if (imports.length === 0) return [];
+
+  const bySource = new Map<string, Set<string>>();
+
+  for (const candidate of imports) {
+    for (const item of candidate.importedItems ?? []) {
+      if (!item) continue;
+      if (schemaBody && !new RegExp(`\\b${escapeRegExp(item)}\\b`).test(schemaBody)) continue;
+      const names = bySource.get(candidate.source) ?? new Set<string>();
+      names.add(item);
+      bySource.set(candidate.source, names);
+    }
+  }
+
+  const build = (source: string, importedItems: string[]): CustomImport => {
+    const importStatement = `import { ${importedItems.join(', ')} } from '${source}'`;
+    return {
+      importStatement,
+      source,
+      importedItems,
+      isDefault: false,
+      isNamespace: false,
+      isTypeOnly: false,
+      originalStatement: importStatement,
+    };
+  };
+
+  return [...bySource.entries()]
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .flatMap(([source, names]) => {
+      const importedItems = [...names].sort();
+      return oneNamePerStatement
+        ? importedItems.map((item) => build(source, [item]))
+        : [build(source, importedItems)];
+    });
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Report a typed-JSON diagnostic once per generate.
+ *
+ * One annotated field reaches a dozen input schemas, so an un-deduplicated warning buries
+ * everything else in the generator's output and trains people to ignore it.
+ */
+const reported = new Set<string>();
+
+export function warnOnce(message: string): void {
+  if (reported.has(message)) return;
+  reported.add(message);
+  logger.warn(`[typedJson] ${message}`);
+}
+
+/**
+ * Log whatever a resolution has to say, at most once each.
+ *
+ * `unconvertible` is the important one: the field silently keeps its old schema, and
+ * without a line in the output the user has no way to tell that their annotation did
+ * nothing.
+ */
+export function reportTypedJsonResult(result: TypedJsonResult, describe: () => string): void {
+  for (const warning of result.warnings) warnOnce(warning);
+
+  if (result.status === 'unconvertible') {
+    warnOnce(result.reason);
+    return;
+  }
+
+  if (result.status === 'resolved' && result.hasZodAnnotations) {
+    warnOnce(
+      `${describe()}: the @zod annotations on this field are not applied, because ` +
+        `${result.annotation.raw} already replaces its base schema.`,
+    );
+  }
+}

package/src/typed-json/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Typed JSON and typed scalar fields, compatible with
+ * prisma-json-types-generator (PJTG).
+ *
+ * Emitters should need only `resolveTypedJsonField`. The parser and the
+ * converter are exported for tests and for anything that wants to inspect an
+ * annotation without resolving it.
+ *
+ * Usage from an emitter, in the position where the base schema is chosen:
+ *
+ * ```ts
+ * const typed = resolveTypedJsonField(
+ *   { modelName, fieldName: field.name, documentation: field.documentation,
+ *     isList: field.isList, outputSubdir: 'schemas/objects' },
+ *   Transformer.getGeneratorConfig()?.typedJson,
+ * );
+ * const baseSchema =
+ *   typed.status === 'resolved' ? typed.elementExpression : (customSchema || 'jsonSchema');
+ * if (typed.status === 'unconvertible') logger.warn(typed.reason);
+ * ```
+ *
+ * `elementExpression` is deliberately the element schema: both the CRUD emitter
+ * and the pure-model emitter apply their own list wrapper afterwards. Use
+ * `expression` only in an emitter that does not.
+ */
+
+export {
+  detectPjtgAnnotation,
+  parsePjtgAnnotation,
+  type PjtgAnnotation,
+  type PjtgAnnotationKind,
+  type PjtgAnnotationParseResult,
+} from './annotation-parser';
+
+export {
+  convertTsTypeToZod,
+  quoteStringLiteral,
+  type TsTypeConversionFailure,
+  type TsTypeConversionOptions,
+  type TsTypeConversionResult,
+  type TsTypeConversionSuccess,
+  type TypeNameResolution,
+} from './ts-type-to-zod';
+
+export {
+  resolveImportSpecifier,
+  resolveTypedJsonField,
+  type TypedJsonFieldContext,
+  type TypedJsonImport,
+  type TypedJsonNone,
+  type TypedJsonResolved,
+  type TypedJsonResult,
+  type TypedJsonSuperseded,
+  type TypedJsonTypeUse,
+  type TypedJsonUnconvertible,
+} from './resolver';
+
+// The configuration block, its defaults, and the `[TypeName]` resolution order
+// live in src/config/typed-json.ts and are re-exported here so an emitter needs
+// only one import. There is one implementation of resolution, not two.
+export {
+  DEFAULT_TYPED_JSON_NAMESPACE,
+  DEFAULT_TYPED_JSON_SCHEMA_SUFFIX,
+  resolveTypedJsonConfig,
+  resolveTypedJsonType,
+  type ResolvedTypedJsonConfig,
+  type TypedJsonConfig,
+  type TypedJsonTypeResolution,
+} from '../config/typed-json';