@algosail/lang 0.2.11 → 0.5.0

package/lib/codegen/emit-jsdoc-sail.js

@@ -0,0 +1,383 @@
+/**
+ * L5 этап 8: JSDoc с `@sail` в сгенерированном ESM (RFC-compile-0.1 §11, RFC-0.1 §10.1).
+ * Тот же контрактный формат, что у ручного FFI: произвольный префикс до `@sail`, затем только Sail.
+ */
+import path from 'node:path'
+
+/**
+ * @param {string} line
+ * @returns {string}
+ */
+function escapeJSDocLine (line) {
+  return line.replace(/\*\//g, '*\\/')
+}
+
+/**
+ * @param {string[]} docEntries inner text of each `-- … --` block
+ * @returns {string} Sail `doc_block` fragments
+ */
+export function formatDocBlocksAsSail (docEntries) {
+  if (!Array.isArray(docEntries) || docEntries.length === 0) return ''
+  return docEntries.map((t) => `-- ${String(t)} --`).join(' ')
+}
+
+/**
+ * @param {string[]} lines prose without leading `*`
+ * @returns {string[]}
+ */
+function proseToStarLines (lines) {
+  const out = []
+  for (const raw of lines) {
+    for (const part of String(raw).split('\n')) {
+      out.push(escapeJSDocLine(part))
+    }
+  }
+  return out
+}
+
+/**
+ * @param {{ proseLines?: string[], sailText: string }} opts
+ * @returns {string}
+ */
+export function formatJSDocSailBlock ({ proseLines = [], sailText }) {
+  const sail = String(sailText).trim()
+  const body = []
+  const prose = proseToStarLines(proseLines)
+  for (const pl of prose) {
+    body.push(` * ${pl}`)
+  }
+  if (prose.length > 0) body.push(' *')
+  body.push(' * @sail')
+  for (const line of sail.split('\n')) {
+    body.push(` * ${line}`)
+  }
+  return `/**\n${body.join('\n')}\n */`
+}
+
+/**
+ * @param {object | null | undefined} expr
+ * @returns {string}
+ */
+export function formatAstTypeExpr (expr) {
+  if (!expr || typeof expr !== 'object') return '_'
+  switch (expr.kind) {
+    case 'type_name':
+      return String(expr.name)
+    case 'type_var':
+      return String(expr.name)
+    case 'module_type_ref':
+      return `~${expr.module}/${expr.type}`
+    case 'paren_type':
+      return `(${formatAstTypeExpr(expr.inner)})`
+    case 'type_app': {
+      const ctor = String(expr.ctor)
+      const args = (expr.args ?? []).map(formatAstTypeExpr)
+      return `${ctor} ${args.join(' ')}`.trim()
+    }
+    case 'quotation_type':
+      return `Quote (${formatAstSignatureText(expr.inner)})`
+    default:
+      return '_'
+  }
+}
+
+/**
+ * @param {object | null | undefined} item
+ * @returns {string}
+ */
+export function formatAstSigStackItem (item) {
+  if (!item || typeof item !== 'object') return '_'
+  switch (item.kind) {
+    case 'stack_var':
+      return `~${item.name}`
+    case 'sig_type_expr':
+      return formatAstTypeExpr(item.type)
+    case 'quotation_sig':
+      return `(${formatAstSignatureText(item.inner)})`
+    case 'named_quotation_sig': {
+      const inner = formatAstSignatureText(item.quotation.inner)
+      return `${item.prefix}: (${inner})`
+    }
+    default:
+      return '_'
+  }
+}
+
+/**
+ * @param {{ offset: number }} a
+ * @param {{ offset: number }} b
+ * @returns {number}
+ */
+function cmpSpan (a, b) {
+  return (a?.offset ?? 0) - (b?.offset ?? 0)
+}
+
+/**
+ * @param {object} sig AstSignature
+ * @returns {string}
+ */
+export function formatAstSignatureText (sig) {
+  if (!sig || typeof sig !== 'object') return '->'
+  const left = (sig.left ?? []).map(formatAstSigStackItem).join(' ')
+  /** @type {{ span: object, emit: () => string }[]} */
+  const rightParts = []
+  for (const it of sig.right ?? []) {
+    const sp = it.span?.start ?? { offset: 0 }
+    rightParts.push({ span: sp, emit: () => formatAstSigStackItem(it) })
+  }
+  for (const e of sig.effectsAdd ?? []) {
+    if (e.side !== 'right') continue
+    const sp = e.span?.start ?? { offset: 0 }
+    rightParts.push({ span: sp, emit: () => `+${e.name}` })
+  }
+  for (const e of sig.effectsRemove ?? []) {
+    if (e.side !== 'right') continue
+    const sp = e.span?.start ?? { offset: 0 }
+    rightParts.push({ span: sp, emit: () => `-${e.name}` })
+  }
+  rightParts.sort((a, b) => cmpSpan(a.span, b.span))
+  const right = rightParts.map((p) => p.emit()).join(' ')
+  if (left.length === 0 && right.length === 0) return '->'
+  if (left.length === 0) return `-> ${right}`.trim()
+  if (right.length === 0) return `${left} ->`.trim()
+  return `${left} -> ${right}`
+}
+
+/**
+ * @param {object | null | undefined} slot normalized / wire slot
+ * @returns {string}
+ */
+export function formatWireTypeSlot (slot) {
+  if (!slot || typeof slot !== 'object') return '_'
+  switch (slot.kind) {
+    case 'prim':
+    case 'opaque':
+      return String(slot.name)
+    case 'tvar':
+      return String(slot.name)
+    case 'stack_label':
+      return `~${slot.name}`
+    case 'mod_adt':
+      return `~${slot.module}/${slot.type}`
+    case 'adt':
+      return String(slot.type)
+    case 'app': {
+      const args = (slot.args ?? []).map(formatWireTypeSlot)
+      return `${slot.ctor} ${args.join(' ')}`.trim()
+    }
+    case 'quote':
+      return `(${formatWireSignatureText(slot.inner)})`
+    case 'named_quote': {
+      const inner = formatWireSignatureText(slot.inner)
+      return `${slot.prefix}: (${inner})`
+    }
+    default:
+      return '_'
+  }
+}
+
+/**
+ * @param {object | null | undefined} sig wire normalizedSig
+ * @returns {string}
+ */
+export function formatWireSignatureText (sig) {
+  if (!sig || typeof sig !== 'object') return '->'
+  const left = (sig.left ?? []).map(formatWireTypeSlot).join(' ')
+  const right = (sig.right ?? []).map(formatWireTypeSlot).join(' ')
+  const adds = (sig.effectsAdd ?? [])
+    .filter((e) => e.side !== 'left')
+    .map((e) => `+${e.name}`)
+  const subs = (sig.effectsRemove ?? [])
+    .filter((e) => e.side !== 'left')
+    .map((e) => `-${e.name}`)
+  const rightAll = [right, ...adds, ...subs].filter(Boolean).join(' ')
+  if (left.length === 0 && rightAll.length === 0) return '->'
+  if (left.length === 0) return `-> ${rightAll}`.trim()
+  if (rightAll.length === 0) return `${left} ->`.trim()
+  return `${left} -> ${rightAll}`
+}
+
+/**
+ * @param {object} item sum_type AST
+ * @returns {string}
+ */
+export function formatSumTypeDeclSail (item) {
+  const params =
+    Array.isArray(item.typeParams) && item.typeParams.length > 0
+      ? ` ${item.typeParams.join(' ')}`
+      : ''
+  const head = `& ${item.name}${params} ${formatDocBlocksAsSail(item.doc ?? [])}`.trimEnd()
+  const lines = [head]
+  for (const tag of item.tags ?? []) {
+    const pl = tag.payload ? ` ${formatAstTypeExpr(tag.payload)}` : ''
+    const piece =
+      `| ${tag.name}${pl} ${formatDocBlocksAsSail(tag.doc ?? [])}`.trimEnd()
+    lines.push(piece)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * @param {object} item product_type AST
+ * @returns {string}
+ */
+export function formatProductTypeDeclSail (item) {
+  const params =
+    Array.isArray(item.typeParams) && item.typeParams.length > 0
+      ? ` ${item.typeParams.join(' ')}`
+      : ''
+  const head = `& ${item.name}${params} ${formatDocBlocksAsSail(item.doc ?? [])}`.trimEnd()
+  const lines = [head]
+  for (const f of item.fields ?? []) {
+    const piece =
+      `: ${f.name} ${formatAstTypeExpr(f.type)} ${formatDocBlocksAsSail(f.doc ?? [])}`.trimEnd()
+    lines.push(piece)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Собирает строки «человеческой» документации до `@sail` (JSDoc префикс).
+ *
+ * @param {string[]} doc
+ * @returns {string[]}
+ */
+function proseFromDocEntries (doc) {
+  if (!Array.isArray(doc) || doc.length === 0) return []
+  return doc.flatMap((d) => String(d).split('\n'))
+}
+
+/**
+ * @param {string} modulePath
+ * @param {import('../typecheck/build-type-env.js').TypecheckEnv} env
+ * @returns {{ ok: true, block: string } | { ok: false, message: string }}
+ */
+export function formatModuleSailHeaderBlock (modulePath, env) {
+  const normPath = path.normalize(modulePath)
+  const snap = env.snapshots?.get(normPath)
+  const scope = env.scopeByPath?.get(normPath)
+  if (!snap?.ok || !Array.isArray(snap.items) || !scope?.exportTypes) {
+    return { ok: true, block: '' }
+  }
+
+  /** @type {string[]} */
+  const proseLines = []
+  /** @type {string[]} */
+  const sailChunks = []
+
+  for (const it of snap.items) {
+    if (it.kind === 'sum_type' && scope.exportTypes.has(it.name)) {
+      proseLines.push(...proseFromDocEntries(it.doc))
+      try {
+        sailChunks.push(formatSumTypeDeclSail(it))
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e)
+        return { ok: false, message: `sum &${it.name}: ${msg}` }
+      }
+    } else if (it.kind === 'product_type' && scope.exportTypes.has(it.name)) {
+      proseLines.push(...proseFromDocEntries(it.doc))
+      try {
+        sailChunks.push(formatProductTypeDeclSail(it))
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e)
+        return { ok: false, message: `product &${it.name}: ${msg}` }
+      }
+    }
+  }
+
+  if (sailChunks.length === 0) {
+    return { ok: true, block: '' }
+  }
+
+  const sailText = sailChunks.join('\n\n')
+  try {
+    const block = formatJSDocSailBlock({
+      proseLines,
+      sailText
+    })
+    return { ok: true, block }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    return { ok: false, message: msg }
+  }
+}
+
+/**
+ * @param {object | null | undefined} snap
+ * @param {string} wordName
+ * @returns {object | null}
+ */
+export function findWordItemInSnapshot (snap, wordName) {
+  if (!snap?.ok || !Array.isArray(snap.items)) return null
+  for (const it of snap.items) {
+    if (it.kind === 'word' && it.name === wordName) return it
+  }
+  return null
+}
+
+/**
+ * @param {{
+ *   wordName: string
+ *   wordAst: object | null
+ *   wireSig: object | null | undefined
+ *   exportAsync?: boolean
+ *   asyncDefinition?: boolean
+ *   mayFail?: boolean
+ * }} opts
+ * @returns {{ ok: true, block: string } | { ok: false, message: string }}
+ */
+export function formatWordSailBlock ({
+  wordName,
+  wordAst,
+  wireSig,
+  exportAsync,
+  asyncDefinition,
+  mayFail
+}) {
+  /** @type {string[]} */
+  const proseLines = []
+  if (wordAst && Array.isArray(wordAst.doc)) {
+    proseLines.push(...proseFromDocEntries(wordAst.doc))
+  }
+
+  let sigText
+  try {
+    if (wordAst?.signature) {
+      sigText = formatAstSignatureText(wordAst.signature)
+    } else if (wireSig) {
+      sigText = formatWireSignatureText(wireSig)
+    } else {
+      return { ok: false, message: `нет сигнатуры для @${wordName}` }
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    return { ok: false, message: msg }
+  }
+
+  const wantAsync =
+    exportAsync === true ||
+    asyncDefinition === true
+  if (wantAsync && !/\+Async\b/.test(sigText)) {
+    sigText = `${sigText} +Async`.trim()
+  }
+  if (mayFail === true && !/\+Fail\b/.test(sigText)) {
+    sigText = `${sigText} +Fail`.trim()
+  }
+
+  const sailDoc = formatDocBlocksAsSail(
+    wordAst && Array.isArray(wordAst.doc) ? wordAst.doc : []
+  )
+  const sailBody = [`@${wordName} ( ${sigText} )`, sailDoc]
+    .filter((s) => s.length > 0)
+    .join(' ')
+
+  try {
+    return {
+      ok: true,
+      block: formatJSDocSailBlock({ proseLines, sailText: sailBody })
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    return { ok: false, message: msg }
+  }
+}