@softize/opus 8.6.6

package/bin/lib/gen-stubs.mjs

@@ -0,0 +1,463 @@
+/**
+ * gen-stubs — emite stubs TypeScript do tipo "ActionDef sem handler" pro
+ * frontend.
+ *
+ * Reconstrói o schema Zod do `input` (e `output` quando útil) a partir do
+ * JSON Schema serializado pelo runner, evitando que o consumer redeclare
+ * schemas só pra usar `useFormAction`. Cobre os tipos básicos (string,
+ * number, boolean, array, object, enum, const, union via anyOf/oneOf,
+ * default, optional via required[]). Refinements custom (.refine,
+ * .transform, .pipe) NÃO viajam via JSON Schema — emite warning no topo
+ * do arquivo pra deixar explícito que o schema reconstruído é approximação.
+ *
+ * Pra metadata extra que o frontend consome (label, icon, color,
+ * messages, fields, emits, invalidates, successStatus), copia direto do
+ * manifest. Closures (`authorize`, `invalidates: () => [...]`) viram
+ * `<function>` no manifest — emitidos como string literal com comment
+ * "// computado em runtime" pra avisar que o stub não roda essa lógica.
+ *
+ * Estrutura emitida (um arquivo por domínio raiz, achata subdomains):
+ *
+ *   // AUTO-GERADO por @softize/opus gen. Não edite.
+ *   // Refinements custom (.refine/.transform/.pipe) NÃO preservados.
+ *   import { z } from 'zod'
+ *   import { defineAction } from '@softize/opus/core'
+ *
+ *   function clientOnly(): never { throw new Error('...') }
+ *
+ *   export const ticketOpen = defineAction({ ... })
+ *
+ * Identifier do export: camelCase do nome (`ticket.open` → `ticketOpen`,
+ * `shipment.flag.create` → `shipmentFlagCreate`).
+ */
+
+export function buildClientStubs(manifest) {
+  const out = []
+  for (const domain of manifest.domains) {
+    out.push({
+      filename: `${domain.name}.ts`,
+      content: renderDomainStubs(domain),
+    })
+  }
+  return out
+}
+
+function renderDomainStubs(domain) {
+  const actions = []
+  collectActions(domain, actions)
+
+  const lines = []
+  lines.push('// AUTO-GERADO por @softize/opus gen. Não edite.')
+  lines.push(`// Domínio raiz: ${domain.name}`)
+  lines.push(
+    '// Schemas Zod abaixo são reconstruções a partir do JSON Schema —',
+  )
+  lines.push(
+    '// refinements custom (.refine / .transform / .pipe) NÃO preservam.',
+  )
+  lines.push('')
+  lines.push("import { z } from 'zod'")
+  lines.push("import { defineAction } from '@softize/opus/core'")
+  lines.push('')
+  lines.push(
+    "function clientOnly(): never { throw new Error('[opus stub] handler chamado no cliente — use o fetchClient pra invocar via HTTP') }",
+  )
+  lines.push('')
+
+  for (const action of actions) {
+    lines.push(...renderActionStub(action))
+    lines.push('')
+  }
+  return lines.join('\n').trimEnd() + '\n'
+}
+
+function collectActions(domain, out) {
+  for (const action of domain.actions) out.push(action)
+  if (Array.isArray(domain.subdomains)) {
+    for (const sub of domain.subdomains) collectActions(sub, out)
+  }
+}
+
+function renderActionStub(action) {
+  const id = toCamelCase(action.name)
+  const lines = []
+  if (typeof action.summary === 'string' && action.summary.length > 0) {
+    lines.push(`/** ${action.summary.replace(/\*\//g, '* /')} */`)
+  }
+  lines.push(`export const ${id} = defineAction({`)
+  lines.push(`  name: ${JSON.stringify(action.name)},`)
+  lines.push(`  kind: ${JSON.stringify(action.kind)},`)
+
+  // Metadata leve antes do schema pra ficar parecido com o source.
+  appendStringProp(lines, 'label', action.label)
+  appendStringProp(lines, 'icon', action.icon)
+  appendStringProp(lines, 'color', action.color)
+  appendStringProp(lines, 'title', action.title)
+  appendStringProp(lines, 'summary', action.summary)
+  if (Array.isArray(action.tags) && action.tags.length > 0) {
+    lines.push(`  tags: ${JSON.stringify(action.tags)},`)
+  }
+  if (
+    action.messages !== null &&
+    action.messages !== undefined &&
+    typeof action.messages === 'object'
+  ) {
+    lines.push(`  messages: ${formatObjectLiteral(action.messages, '  ')},`)
+  }
+  if (typeof action.successStatus === 'number') {
+    lines.push(`  successStatus: ${action.successStatus},`)
+  }
+  if (action.public === true) lines.push('  public: true,')
+  if (action.internal === true) lines.push('  internal: true,')
+  if (
+    (action.kind === 'simple' || action.kind === 'form') &&
+    action.background === true
+  ) {
+    lines.push('  background: { enabled: true },')
+  }
+  if (
+    (action.kind === 'simple' || action.kind === 'form') &&
+    Array.isArray(action.emits) &&
+    action.emits.length > 0
+  ) {
+    lines.push(`  emits: ${JSON.stringify(action.emits)},`)
+  }
+  if (action.permission !== null && action.permission !== undefined) {
+    lines.push(`  requires: ${JSON.stringify(action.permission)},`)
+  }
+
+  // input/output — Zod reconstruído.
+  const inputExpr = renderZodFromJsonSchema(action.input, /*indent*/ '  ')
+  lines.push(`  input: ${inputExpr},`)
+  const outputExpr = renderZodFromJsonSchema(action.output, /*indent*/ '  ')
+  lines.push(`  output: ${outputExpr} as never,`)
+
+  if (action.kind === 'form') {
+    const fields = stripNullsFromFields(action.fields)
+    if (Object.keys(fields).length > 0) {
+      lines.push(`  fields: ${formatObjectLiteral(fields, '  ')},`)
+    } else {
+      lines.push('  fields: {} as never,')
+    }
+  }
+  if (action.kind === 'view') {
+    const projection = Array.isArray(action.projection) ? action.projection : []
+    lines.push(`  projection: ${JSON.stringify(projection)},`)
+  }
+  if (action.kind === 'list') {
+    if (action.filters && Object.keys(action.filters).length > 0) {
+      const filters = stripNullsFromFields(action.filters)
+      lines.push(`  filters: ${formatObjectLiteral(filters, '  ')},`)
+    }
+  }
+  if (Array.isArray(action.invalidates) && action.invalidates.length > 0) {
+    lines.push(`  invalidates: ${JSON.stringify(action.invalidates)},`)
+  } else if (action.invalidates === '<function>') {
+    lines.push('  // invalidates: computado em runtime — não preservado no stub')
+  }
+
+  lines.push('  handler: clientOnly,')
+  lines.push('})')
+  return lines
+}
+
+function appendStringProp(lines, key, value) {
+  if (typeof value !== 'string' || value.length === 0) return
+  lines.push(`  ${key}: ${JSON.stringify(value)},`)
+}
+
+/**
+ * Field/filter specs vêm do manifest com todos os slots em null.
+ * Remove os nulls e drops `hasShowWhen`/`hasRequireWhen` (são meta-flags
+ * do runner, não viajam pro stub).
+ */
+function stripNullsFromFields(record) {
+  if (record === null || record === undefined || typeof record !== 'object') {
+    return {}
+  }
+  const out = {}
+  for (const [name, spec] of Object.entries(record)) {
+    if (spec === null || typeof spec !== 'object') continue
+    const clean = {}
+    for (const [k, v] of Object.entries(spec)) {
+      if (v === null || v === undefined) continue
+      if (k === 'hasShowWhen' || k === 'hasRequireWhen') continue
+      if (typeof v === 'boolean' && v === false) continue
+      clean[k] = v
+    }
+    out[name] = clean
+  }
+  return out
+}
+
+/**
+ * Serializa um objeto JS plano como literal TS indentado.
+ * Valores são serializados via JSON.stringify (seguro pra strings com
+ * aspas, booleans, numbers, arrays e objetos aninhados).
+ */
+function formatObjectLiteral(obj, indent) {
+  const inner = indent + '  '
+  const entries = Object.entries(obj)
+  if (entries.length === 0) return '{}'
+  const lines = ['{']
+  for (const [k, v] of entries) {
+    lines.push(`${inner}${formatKey(k)}: ${formatValue(v, inner)},`)
+  }
+  lines.push(`${indent}}`)
+  return lines.join('\n')
+}
+
+function formatValue(value, indent) {
+  if (value === null || value === undefined) return 'null'
+  if (typeof value === 'string') return JSON.stringify(value)
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) return JSON.stringify(value)
+  if (typeof value === 'object') return formatObjectLiteral(value, indent)
+  return JSON.stringify(value)
+}
+
+function formatKey(key) {
+  if (typeof key !== 'string') return JSON.stringify(String(key))
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) return key
+  return JSON.stringify(key)
+}
+
+// =============================================================================
+// JSON Schema → Zod
+// =============================================================================
+
+/**
+ * Reconstrói expressão Zod a partir do JSON Schema serializado.
+ * Fallback pra `z.any()` quando shape não é reconhecido. NUNCA lança —
+ * pra evitar emitir arquivo broken; pior caso, devolve `z.any()`.
+ */
+function renderZodFromJsonSchema(schema, indent) {
+  if (schema === null || schema === undefined) return 'z.any()'
+  if (typeof schema !== 'object') return 'z.any()'
+  if (schema.__unserializable === true) return 'z.any()'
+
+  // const X
+  if (Object.prototype.hasOwnProperty.call(schema, 'const')) {
+    const expr = `z.literal(${JSON.stringify(schema.const)})`
+    return wrapDefault(expr, schema)
+  }
+
+  // enum-only (sem type)
+  if (Array.isArray(schema.enum) && schema.type === undefined) {
+    const expr = renderEnum(schema.enum)
+    return wrapDefault(expr, schema)
+  }
+
+  // anyOf / oneOf → z.union
+  if (Array.isArray(schema.anyOf) || Array.isArray(schema.oneOf)) {
+    const branches = schema.anyOf ?? schema.oneOf
+    const rendered = branches.map((b) => renderZodFromJsonSchema(b, indent + '  '))
+    let expr
+    if (rendered.length === 1) {
+      expr = rendered[0]
+    } else if (rendered.length === 2) {
+      expr = `z.union([${rendered.join(', ')}])`
+    } else {
+      expr = `z.union([\n${indent}  ${rendered.join(`,\n${indent}  `)},\n${indent}])`
+    }
+    return wrapDefault(expr, schema)
+  }
+
+  // allOf → tentar merge object schemas; fallback pra z.any().
+  if (Array.isArray(schema.allOf)) {
+    // Heurística simples: se todos são objetos, mescla properties+required.
+    const merged = mergeAllOf(schema.allOf)
+    if (merged !== null) {
+      return renderZodFromJsonSchema(merged, indent)
+    }
+    return 'z.any()'
+  }
+
+  const t = schema.type
+  // type array (ex: ["string", "null"]) → union escalar.
+  if (Array.isArray(t)) {
+    const branches = t.map((tn) =>
+      renderZodFromJsonSchema({ ...schema, type: tn }, indent + '  '),
+    )
+    const expr = branches.length === 1 ? branches[0] : `z.union([${branches.join(', ')}])`
+    return wrapDefault(expr, schema)
+  }
+
+  if (t === 'string') {
+    let expr = renderStringSchema(schema)
+    return wrapDefault(expr, schema)
+  }
+
+  if (t === 'integer' || t === 'number') {
+    let expr = 'z.number()'
+    if (t === 'integer') expr += '.int()'
+    if (typeof schema.minimum === 'number') expr += `.min(${schema.minimum})`
+    if (typeof schema.maximum === 'number') expr += `.max(${schema.maximum})`
+    if (typeof schema.exclusiveMinimum === 'number') {
+      expr += `.gt(${schema.exclusiveMinimum})`
+    }
+    if (typeof schema.exclusiveMaximum === 'number') {
+      expr += `.lt(${schema.exclusiveMaximum})`
+    }
+    return wrapDefault(expr, schema)
+  }
+
+  if (t === 'boolean') {
+    return wrapDefault('z.boolean()', schema)
+  }
+
+  if (t === 'null') {
+    return wrapDefault('z.null()', schema)
+  }
+
+  if (t === 'array') {
+    const items = schema.items
+    const inner = renderZodFromJsonSchema(items, indent + '  ')
+    let expr = `z.array(${inner})`
+    if (typeof schema.minItems === 'number') expr += `.min(${schema.minItems})`
+    if (typeof schema.maxItems === 'number') expr += `.max(${schema.maxItems})`
+    return wrapDefault(expr, schema)
+  }
+
+  if (t === 'object') {
+    return renderObjectSchema(schema, indent)
+  }
+
+  // Sem type mas com properties → object implícito.
+  if (
+    typeof schema.properties === 'object' &&
+    schema.properties !== null
+  ) {
+    return renderObjectSchema({ ...schema, type: 'object' }, indent)
+  }
+
+  return 'z.any()'
+}
+
+function renderStringSchema(schema) {
+  // Casos especiais por format.
+  if (schema.format === 'date-time') {
+    let expr = 'z.string().datetime()'
+    return expr
+  }
+  let expr = 'z.string()'
+  if (typeof schema.minLength === 'number') {
+    expr += `.min(${schema.minLength})`
+  }
+  if (typeof schema.maxLength === 'number') {
+    expr += `.max(${schema.maxLength})`
+  }
+  if (typeof schema.pattern === 'string') {
+    // Regex preservada como `RegExp` literal. Escape de slashes resolvido
+    // por JSON.stringify + casting via `new RegExp`.
+    expr += `.regex(new RegExp(${JSON.stringify(schema.pattern)}))`
+  }
+  if (typeof schema.format === 'string') {
+    if (schema.format === 'email') expr += '.email()'
+    else if (schema.format === 'uri') expr += '.url()'
+    else if (schema.format === 'uuid') expr += '.uuid()'
+    // outros formats viram `as any` no zod, ignorados.
+  }
+  if (Array.isArray(schema.enum)) {
+    // type: 'string' + enum → z.enum
+    return renderEnum(schema.enum)
+  }
+  return expr
+}
+
+function renderObjectSchema(schema, indent) {
+  const props = schema.properties
+  if (props === null || typeof props !== 'object') {
+    return 'z.object({})'
+  }
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required : [],
+  )
+  const inner = indent + '  '
+  const lines = ['z.object({']
+  for (const [key, prop] of Object.entries(props)) {
+    let value = renderZodFromJsonSchema(prop, inner)
+    const isReq = required.has(key)
+    // Detecta nullable do JSON Schema (target openApi3 usa `nullable: true`).
+    if (prop && typeof prop === 'object' && prop.nullable === true) {
+      value += '.nullable()'
+    }
+    const hasDefault =
+      prop !== null &&
+      typeof prop === 'object' &&
+      Object.prototype.hasOwnProperty.call(prop, 'default')
+    // `.default()` já implica opcional no input; evita encadear `.optional()` redundante.
+    if (!isReq && !hasDefault) value += '.optional()'
+    lines.push(`${inner}${formatKey(key)}: ${value},`)
+  }
+  lines.push(`${indent}})`)
+  let expr = lines.join('\n')
+  // additionalProperties: true → .passthrough(); false (default no zod) já vem.
+  if (schema.additionalProperties === true) {
+    expr += '.passthrough()'
+  }
+  return wrapDefault(expr, schema)
+}
+
+/**
+ * Detecta enum de strings e emite `z.enum([...])`; fallback union de
+ * literais pra outros tipos.
+ */
+function renderEnum(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    return 'z.never()'
+  }
+  const allStrings = values.every((v) => typeof v === 'string')
+  if (allStrings) {
+    // `as const` ajuda inferência mas zod aceita literal-array direto.
+    return `z.enum([${values.map((v) => JSON.stringify(v)).join(', ')}])`
+  }
+  const literals = values.map((v) => `z.literal(${JSON.stringify(v)})`)
+  if (literals.length === 1) return literals[0]
+  return `z.union([${literals.join(', ')}])`
+}
+
+function wrapDefault(expr, schema) {
+  if (!Object.prototype.hasOwnProperty.call(schema, 'default')) return expr
+  const def = schema.default
+  return `${expr}.default(${JSON.stringify(def)})`
+}
+
+/**
+ * Tenta achatar `allOf` mesclando properties+required de schemas-objeto.
+ * Retorna null se qualquer branch não for objeto.
+ */
+function mergeAllOf(branches) {
+  if (!Array.isArray(branches) || branches.length === 0) return null
+  const merged = { type: 'object', properties: {}, required: [] }
+  for (const b of branches) {
+    if (b === null || typeof b !== 'object') return null
+    if (b.type !== 'object' && b.type !== undefined) return null
+    if (typeof b.properties === 'object' && b.properties !== null) {
+      Object.assign(merged.properties, b.properties)
+    }
+    if (Array.isArray(b.required)) {
+      for (const r of b.required) {
+        if (!merged.required.includes(r)) merged.required.push(r)
+      }
+    }
+  }
+  return merged
+}
+
+/**
+ * `ticket.open` → `ticketOpen`. `shipment.flag.create` → `shipmentFlagCreate`.
+ * Mantém prefixo do nome — não tem colisão em domínio raiz pq actions são
+ * globalmente únicas no `defineDomain`.
+ */
+function toCamelCase(name) {
+  const parts = name.split('.')
+  if (parts.length === 0) return name
+  return parts
+    .map((p, i) =>
+      i === 0 ? p : p.charAt(0).toUpperCase() + p.slice(1),
+    )
+    .join('')
+}