@algosail/lang 0.2.11 → 0.5.0

package/lib/codegen/emit-module.js

@@ -0,0 +1,498 @@
+/**
+ * L5 этап 3: один модуль `.sail` → один ESM (RFC-compile-0.1 §9, RFC-IR §7).
+ */
+import path from 'node:path'
+import { buildModuleIr } from '../ir/index.js'
+import {
+  calleeAsyncPropagatesToCaller,
+  declaredEffectFlags
+} from '../typecheck/effect-decl.js'
+import { buildAutogenSignaturesForModule } from '../typecheck/adt-autogen-sigs.js'
+import {
+  emitAdtAutogenFunctionBody,
+  findAutogenRoleInModule,
+  formatAutogenFormalParameters,
+  mangleQualifiedAutogenName
+} from './emit-adt.js'
+import {
+  emitWordBodyIr,
+  formatFormalParametersForWireSig,
+  irStepsCallsPropagatingAsyncCallee
+} from './emit-body.js'
+import { relativeSpecifierFromOutputs } from './esm-imports.js'
+import {
+  e5201BadImportAlias,
+  e5202ImportEmptySpecifier,
+  e5203BadBracketWord,
+  e5204BadJsWordName,
+  e5205EmitAdtAutogen,
+  e5205EmitWord,
+  e5206JSDocModuleHeader,
+  e5206JSDocWord
+} from './codegen-diagnostics.js'
+import {
+  formatModuleSailHeaderBlock,
+  formatWordSailBlock,
+  findWordItemInSnapshot
+} from './emit-jsdoc-sail.js'
+import { projectJsFileToOutputPath, sailModuleToOutputJsPath } from './out-layout.js'
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isValidJsIdentifier (name) {
+  return /^[A-Za-z_$][\w$]*$/.test(name)
+}
+
+/**
+ * @param {unknown} sig
+ * @returns {boolean}
+ */
+function sigPropagatesAsyncToCaller (sig) {
+  if (sig == null || typeof sig !== 'object') return false
+  return calleeAsyncPropagatesToCaller(declaredEffectFlags(sig))
+}
+
+/**
+ * Резолвер сигнатур для `await` при варианте B (IR без `calleeAsync` под `-Async`).
+ *
+ * @param {object} env
+ * @param {string} normModulePath
+ * @param {{ imports?: object[], words?: object[] }} payload
+ */
+export function createCalleeAsyncResolverForModule (env, normModulePath, payload) {
+  const sigByPath = env.sigIrByPath
+  const localMap = sigByPath?.get(normModulePath)
+  /** @type {Map<string, string>} */
+  const aliasToResolved = new Map()
+  for (const imp of payload.imports ?? []) {
+    if (
+      typeof imp.module === 'string' &&
+      typeof imp.resolvedPath === 'string'
+    ) {
+      aliasToResolved.set(imp.module, path.normalize(imp.resolvedPath))
+    }
+  }
+  return {
+    localPropagatesAsync (name) {
+      const s = localMap?.get(name)
+      return sigPropagatesAsyncToCaller(s)
+    },
+    qualifiedPropagatesAsync (moduleAlias, wordName) {
+      const rp = aliasToResolved.get(moduleAlias)
+      if (rp == null) return false
+      const m = sigByPath?.get(rp)
+      const s = m?.get(wordName)
+      return sigPropagatesAsyncToCaller(s)
+    }
+  }
+}
+
+/**
+ * @param {string} body
+ * @param {number} indentWidth
+ * @returns {string}
+ */
+function indentBody (body, indentWidth = 2) {
+  const pad = ' '.repeat(indentWidth)
+  return body
+    .split('\n')
+    .map((line) => (line.length === 0 ? line : pad + line))
+    .join('\n')
+}
+
+/**
+ * @param {unknown} steps
+ * @param {(w: { kind: 'local', name: string } | { kind: 'qualified', module: string, word: string }) => void} visit
+ */
+function walkIrStepsForWordRefs (steps, visit) {
+  if (!Array.isArray(steps)) return
+  for (const raw of steps) {
+    if (raw == null || typeof raw !== 'object') continue
+    const n = /** @type {Record<string, unknown>} */ (raw)
+    const k = String(n.kind ?? '')
+    if (k === 'Word') {
+      const ref = n.ref
+      if (ref === 'local' && typeof n.name === 'string') {
+        visit({ kind: 'local', name: n.name })
+      } else if (
+        ref === 'qualified' &&
+        typeof n.module === 'string' &&
+        typeof (n.word ?? n.name) === 'string'
+      ) {
+        visit({
+          kind: 'qualified',
+          module: n.module,
+          word: String(n.word ?? n.name)
+        })
+      }
+    }
+    if (k === 'Builtin' && n.name === 'call') {
+      const meta = n.callInlineMeta
+      if (meta != null && typeof meta === 'object') {
+        const m = /** @type {{ kind?: string, innerSteps?: unknown }} */ (meta)
+        if (m.kind === 'inline' || m.kind == null) {
+          walkIrStepsForWordRefs(m.innerSteps, visit)
+        }
+      }
+    }
+    if (k === 'Quotation') {
+      const qm = n.quoteEmitMeta
+      if (qm != null && typeof qm === 'object') {
+        walkIrStepsForWordRefs(
+          /** @type {{ innerSteps?: unknown }} */ (qm).innerSteps,
+          visit
+        )
+      }
+    }
+  }
+}
+
+/**
+ * @param {import('../typecheck/build-type-env.js').TypecheckEnv} env
+ * @param {string} normPath
+ * @param {Map<string, unknown> | undefined} wordsMap
+ * @param {{ imports?: object[], words?: object[] }} payload
+ * @param {Map<string, Set<string>>} bracketWordsByAlias
+ */
+function collectAdtAutogenToEmit (
+  env,
+  normPath,
+  wordsMap,
+  payload,
+  bracketWordsByAlias
+) {
+  /** @type {Map<string, { role: object, sig: object }>} */
+  const localFns = new Map()
+  /** @type {Map<string, { role: object, sig: object, mangled: string }>} */
+  const qualFns = new Map()
+  /** @type {Map<string, string>} */
+  const qualCallee = new Map()
+
+  const userNames =
+    wordsMap instanceof Map ? new Set(wordsMap.keys()) : new Set()
+
+  const autoHere = buildAutogenSignaturesForModule(env, normPath)
+
+  /** @type {Map<string, string>} */
+  const aliasToPath = new Map()
+  for (const imp of payload.imports ?? []) {
+    if (
+      typeof imp.module === 'string' &&
+      typeof imp.resolvedPath === 'string'
+    ) {
+      aliasToPath.set(imp.module, path.normalize(imp.resolvedPath))
+    }
+  }
+
+  const considerLocal = (name) => {
+    if (userNames.has(name)) return
+    if (!autoHere.has(name)) return
+    const role = findAutogenRoleInModule(env, normPath, name)
+    if (!role) return
+    localFns.set(name, { role, sig: autoHere.get(name) })
+  }
+
+  const considerQual = (alias, w) => {
+    const bracket = bracketWordsByAlias.get(alias)
+    if (bracket?.has(w)) {
+      qualCallee.set(`${alias}\0${w}`, w)
+      return
+    }
+    const rp = aliasToPath.get(alias)
+    if (rp == null) return
+    const autoThere = buildAutogenSignaturesForModule(env, rp)
+    if (!autoThere.has(w)) return
+    const role = findAutogenRoleInModule(env, rp, w)
+    if (!role) return
+    const mangled = mangleQualifiedAutogenName(alias, w)
+    qualFns.set(`${alias}\0${w}`, {
+      role,
+      sig: autoThere.get(w),
+      mangled
+    })
+    qualCallee.set(`${alias}\0${w}`, mangled)
+  }
+
+  for (const word of payload.words ?? []) {
+    walkIrStepsForWordRefs(word.irSteps, (ref) => {
+      if (ref.kind === 'local') considerLocal(ref.name)
+      else considerQual(ref.module, ref.word)
+    })
+  }
+
+  return { localFns, qualFns, qualCallee }
+}
+
+/**
+ * @param {Map<string, { role: object, sig: object }>} localFns
+ * @param {Map<string, { role: object, sig: object, mangled: string }>} qualFns
+ */
+function emitAutogenBlock (localFns, qualFns) {
+  /** @type {string[]} */
+  const lines = []
+  const localNames = [...localFns.keys()].sort()
+  for (const nm of localNames) {
+    const { role, sig } = localFns.get(nm)
+    const body = emitAdtAutogenFunctionBody(role, sig)
+    const params = formatAutogenFormalParameters(role, sig)
+    const indented = indentBody(body)
+    lines.push(`function ${nm}(${params}) {\n${indented}\n}`)
+  }
+  const qualKeys = [...qualFns.keys()].sort()
+  for (const k of qualKeys) {
+    const { role, sig, mangled } = qualFns.get(k)
+    const body = emitAdtAutogenFunctionBody(role, sig)
+    const params = formatAutogenFormalParameters(role, sig)
+    const indented = indentBody(body)
+    lines.push(`function ${mangled}(${params}) {\n${indented}\n}`)
+  }
+  return lines.join('\n\n')
+}
+
+/**
+ * @param {{
+ *   env: object
+ *   modulePath: string
+ *   layout: { outDir: string, sourceRoot: string, entryPath?: string }
+ * }} opts
+ * @returns {{ ok: true, source: string } | { ok: false, diagnostics: object[] }}
+ */
+export function emitModuleEsmSource ({ env, modulePath, layout }) {
+  const normPath = path.normalize(modulePath)
+  const oa = sailModuleToOutputJsPath(layout, normPath)
+  if (!oa.ok) {
+    return { ok: false, diagnostics: [oa.diagnostic] }
+  }
+
+  const payload = buildModuleIr(env, normPath, {
+    moduleStatus: 'ok',
+    valueBindings: true
+  })
+
+  /** @type {Map<string, Set<string>>} */
+  const bracketWordsByAlias = new Map()
+  for (const imp of payload.imports ?? []) {
+    const words = imp.bracket?.words
+    if (Array.isArray(words) && words.length > 0) {
+      bracketWordsByAlias.set(imp.module, new Set(words))
+    }
+  }
+
+  const wordsMap = env.wordDeclByPath?.get(normPath)
+  const { localFns: autogenLocalFns, qualFns: autogenQualFns, qualCallee } =
+    collectAdtAutogenToEmit(
+      env,
+      normPath,
+      wordsMap,
+      payload,
+      bracketWordsByAlias
+    )
+
+  /** @type {Set<string>} */
+  const sumEliminatorNames = new Set()
+  for (const [name, { sig }] of autogenLocalFns) {
+    if (
+      sig != null &&
+      typeof sig === 'object' &&
+      /** @type {{ adtEliminator?: string }} */ (sig).adtEliminator === 'sum'
+    ) {
+      sumEliminatorNames.add(name)
+    }
+  }
+
+  /** @type {(moduleAlias: string, wordName: string) => string} */
+  const resolveQualifiedCallee = (moduleAlias, wordName) => {
+    const qk = `${moduleAlias}\0${wordName}`
+    if (qualCallee.has(qk)) return qualCallee.get(qk)
+    const set = bracketWordsByAlias.get(moduleAlias)
+    if (set?.has(wordName)) {
+      return wordName
+    }
+    return `${moduleAlias}.${wordName}`
+  }
+
+  /** @type {string[]} */
+  const importLines = []
+  for (const imp of payload.imports ?? []) {
+    const alias = imp.module
+    if (!isValidJsIdentifier(alias)) {
+      return {
+        ok: false,
+        diagnostics: [e5201BadImportAlias(String(alias))]
+      }
+    }
+    const rp = imp.resolvedPath
+    /** @type {string} */
+    let spec
+    if (typeof rp === 'string' && rp.toLowerCase().endsWith('.sail')) {
+      const ob = sailModuleToOutputJsPath(layout, rp)
+      if (!ob.ok) {
+        return { ok: false, diagnostics: [ob.diagnostic] }
+      }
+      spec = relativeSpecifierFromOutputs(oa.path, ob.path)
+    } else if (typeof rp === 'string' && rp.toLowerCase().endsWith('.js')) {
+      const declPath = typeof imp.path === 'string' ? imp.path : ''
+      const isRelativeProjectFfi =
+        declPath.startsWith('./') || declPath.startsWith('../')
+      if (!isRelativeProjectFfi && declPath !== '') {
+        spec = declPath
+      } else {
+        const ob = projectJsFileToOutputPath(layout, rp)
+        if (!ob.ok) {
+          return { ok: false, diagnostics: [ob.diagnostic] }
+        }
+        spec = relativeSpecifierFromOutputs(oa.path, ob.path)
+      }
+    } else {
+      spec = typeof imp.path === 'string' ? imp.path : ''
+      if (spec === '') {
+        return {
+          ok: false,
+          diagnostics: [e5202ImportEmptySpecifier(String(alias))]
+        }
+      }
+    }
+    const quotedSpec = JSON.stringify(spec)
+    const bw = imp.bracket?.words
+    // bracket.types: runtime import откладывается до ADT/codegen этапа 6
+    if (Array.isArray(bw) && bw.length > 0) {
+      for (const w of bw) {
+        if (!isValidJsIdentifier(w)) {
+          return {
+            ok: false,
+            diagnostics: [e5203BadBracketWord(String(w))]
+          }
+        }
+      }
+      importLines.push(`import { ${bw.join(', ')} } from ${quotedSpec};`)
+    } else {
+      importLines.push(`import * as ${alias} from ${quotedSpec};`)
+    }
+  }
+
+  /** @type {string[]} */
+  const funcParts = []
+  const words = Array.isArray(payload.words) ? [...payload.words] : []
+  words.sort((a, b) => String(a.name).localeCompare(String(b.name)))
+
+  const snap = env.snapshots?.get(normPath)
+
+  const headerRes = formatModuleSailHeaderBlock(normPath, env)
+  if (!headerRes.ok) {
+    return {
+      ok: false,
+      diagnostics: [e5206JSDocModuleHeader(headerRes.message)]
+    }
+  }
+  /** @type {string} */
+  const moduleJSDocBlock = headerRes.block
+
+  const calleeAsyncResolver = createCalleeAsyncResolverForModule(
+    env,
+    normPath,
+    payload
+  )
+
+  /** @type {string} */
+  let autogenBlock = ''
+  if (autogenLocalFns.size > 0 || autogenQualFns.size > 0) {
+    try {
+      autogenBlock = emitAutogenBlock(autogenLocalFns, autogenQualFns)
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      return {
+        ok: false,
+        diagnostics: [e5205EmitAdtAutogen(msg)]
+      }
+    }
+  }
+
+  for (const word of words) {
+    if (!word.sigAvailable || word.normalizedSig == null) continue
+    if (!Array.isArray(word.irSteps)) continue
+    const wname = String(word.name)
+    if (!isValidJsIdentifier(wname)) {
+      return {
+        ok: false,
+        diagnostics: [e5204BadJsWordName(wname)]
+      }
+    }
+
+    const needsAsyncKeyword =
+      word.asyncDefinition === true ||
+      irStepsCallsPropagatingAsyncCallee(word.irSteps, calleeAsyncResolver)
+
+    let bodyResult
+    try {
+      bodyResult = emitWordBodyIr(word.irSteps, {
+        strict: true,
+        wordName: wname,
+        normalizedSig: word.normalizedSig,
+        entryStackIds: word.entryStackIds ?? null,
+        resolveQualifiedCallee,
+        callerAsync: needsAsyncKeyword,
+        calleeAsyncResolver,
+        sumEliminatorNames
+      })
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      return {
+        ok: false,
+        diagnostics: [e5205EmitWord(wname, msg)]
+      }
+    }
+
+    const params = formatFormalParametersForWireSig(
+      word.normalizedSig,
+      word.entryStackIds ?? null
+    )
+    const asyncKw = needsAsyncKeyword ? 'async ' : ''
+    const exportKw = word.exported === true ? 'export ' : ''
+    const indented = indentBody(bodyResult.source)
+
+    let exportJSDoc = ''
+    if (word.exported === true) {
+      const wordAst = findWordItemInSnapshot(snap, wname)
+      const blockRes = formatWordSailBlock({
+        wordName: wname,
+        wordAst,
+        wireSig: word.normalizedSig,
+        exportAsync: needsAsyncKeyword,
+        asyncDefinition: word.asyncDefinition === true,
+        mayFail: word.mayFail === true
+      })
+      if (!blockRes.ok) {
+        return {
+          ok: false,
+          diagnostics: [e5206JSDocWord(wname, blockRes.message)]
+        }
+      }
+      exportJSDoc = `${blockRes.block}\n`
+    }
+
+    funcParts.push(
+      `${exportJSDoc}${exportKw}${asyncKw}function ${wname}(${params}) {\n${indented}\n}`
+    )
+  }
+
+  const pieces = []
+  if (importLines.length > 0) {
+    pieces.push(importLines.join('\n'))
+  }
+  if (moduleJSDocBlock.length > 0) {
+    if (pieces.length > 0) pieces.push('')
+    pieces.push(moduleJSDocBlock)
+  }
+  if (autogenBlock.length > 0) {
+    if (pieces.length > 0) pieces.push('')
+    pieces.push(autogenBlock)
+  }
+  if (funcParts.length > 0) {
+    if (pieces.length > 0) pieces.push('')
+    pieces.push(funcParts.join('\n\n'))
+  }
+  const source = pieces.length > 0 ? `${pieces.join('\n')}\n` : '\n'
+  return { ok: true, source }
+}

package/lib/codegen/esm-imports.js

@@ -0,0 +1,26 @@
+/**
+ * Статические спецификаторы ESM между артефактами под out-dir (RFC-compile-0.1 §9.2).
+ */
+import path from 'node:path'
+
+/**
+ * Относительный спецификатор от `dirname(O_A)` к `O_B` с префиксом `./` или `../`
+ * и путём в стиле URL (прямые слэши).
+ *
+ * @param {string} fromOutJsPath — абсолютный путь к выходному `.js` текущего модуля
+ * @param {string} toOutJsPath — абсолютный путь к выходному `.js` зависимости
+ * @returns {string}
+ */
+export function relativeSpecifierFromOutputs (fromOutJsPath, toOutJsPath) {
+  const fromDir = path.dirname(path.resolve(fromOutJsPath))
+  const toAbs = path.resolve(toOutJsPath)
+  let rel = path.relative(fromDir, toAbs)
+  if (!rel || rel === '') {
+    rel = path.basename(toAbs)
+  }
+  rel = rel.split(path.sep).join('/')
+  if (!rel.startsWith('.')) {
+    rel = `./${rel}`
+  }
+  return rel
+}

package/lib/codegen/index.js

@@ -0,0 +1,69 @@
+/**
+ * L5 codegen: вход после L3 (RFC-compile-0.1 §4, RFC-IR-0.1 §1.1).
+ */
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { typecheckSail } from '../typecheck/index.js'
+import { emitCodegenStage0Stub } from './compile-graph.js'
+import { resolveCompileLayout, validateEntryInsideSourceRoot } from './out-layout.js'
+
+export { emitCodegenStage0Stub } from './compile-graph.js'
+export { emitWordBodyIr, formatFormalParametersForWireSig } from './emit-body.js'
+export { emitModuleEsmSource } from './emit-module.js'
+export { relativeSpecifierFromOutputs } from './esm-imports.js'
+export {
+  isPathInsideSourceRoot,
+  projectJsFileToOutputPath,
+  resolveCompileLayout,
+  sailModuleToOutputJsPath,
+  validateEntryInsideSourceRoot
+} from './out-layout.js'
+
+function defaultFsSink () {
+  return {
+    mkdir: (p, opts) => fs.mkdir(p, opts),
+    writeFile: (p, data) => fs.writeFile(p, data, 'utf8')
+  }
+}
+
+/**
+ * Компиляция точки входа: typecheck; при `ok` — эмиссия ESM по модулям замыкания (этап 3).
+ *
+ * @param {{
+ *   entryPath: string,
+ *   outDir: string,
+ *   sourceRoot?: string,
+ *   readFile: (p: string) => string | null | undefined,
+ *   resolvePackage?: (spec: string, fromPath: string) => string | null,
+ *   fs?: {
+ *     mkdir: (p: string, opts?: { recursive?: boolean }) => Promise<void>,
+ *     writeFile: (p: string, data: string) => Promise<void>
+ *   }
+ * }} opts
+ * @returns {Promise<
+ *   | { ok: false, diagnostics: object[] }
+ *   | { ok: true, diagnostics: [], emitted: string[] }
+ * >}
+ */
+export async function compileSailToOutDir (opts) {
+  const entryPath = path.resolve(opts.entryPath)
+  const tc = typecheckSail({
+    entryPath,
+    readFile: opts.readFile,
+    resolvePackage: opts.resolvePackage
+  })
+  if (!tc.ok) {
+    return { ok: false, diagnostics: tc.diagnostics }
+  }
+  const layout = resolveCompileLayout({
+    entryPath,
+    outDir: opts.outDir,
+    sourceRoot: opts.sourceRoot
+  })
+  const entryLayoutOk = validateEntryInsideSourceRoot(layout)
+  if (!entryLayoutOk.ok) {
+    return { ok: false, diagnostics: entryLayoutOk.diagnostics }
+  }
+  const fsSink = opts.fs ?? defaultFsSink()
+  return emitCodegenStage0Stub(tc.env, layout, fsSink, opts.readFile)
+}

package/lib/codegen/out-layout.js

@@ -0,0 +1,102 @@
+/**
+ * Раскладка выходных путей (RFC-compile-0.1 §9.2): source-root, O(S) для `.sail` → `.js`.
+ */
+import path from 'node:path'
+import {
+  e5101SailInvalidRelative,
+  e5101SailOutsideSourceRoot,
+  e5102SailExpectedExtension,
+  e5103FfiInvalidRelative,
+  e5103FfiOutsideSourceRoot,
+  e5104FfiExpectedExtension,
+  e5105EntryOutsideSourceRoot
+} from './codegen-diagnostics.js'
+
+/**
+ * @param {{ entryPath: string, outDir: string, sourceRoot?: string }} opts
+ * @returns {{ entryPath: string, outDir: string, sourceRoot: string }}
+ */
+export function resolveCompileLayout (opts) {
+  const entryPath = path.resolve(opts.entryPath)
+  const outDir = path.resolve(opts.outDir)
+  const sourceRoot =
+    opts.sourceRoot != null ? path.resolve(opts.sourceRoot) : path.dirname(entryPath)
+  return { entryPath, outDir, sourceRoot }
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} sourceRoot
+ * @returns {boolean}
+ */
+export function isPathInsideSourceRoot (filePath, sourceRoot) {
+  const f = path.resolve(filePath)
+  const r = path.resolve(sourceRoot)
+  const prefix = r.endsWith(path.sep) ? r : r + path.sep
+  return f === r || f.startsWith(prefix)
+}
+
+/**
+ * @param {{ entryPath: string, sourceRoot: string } & object} layout
+ * @returns {{ ok: true } | { ok: false, diagnostics: object[] }}
+ */
+export function validateEntryInsideSourceRoot (layout) {
+  if (!isPathInsideSourceRoot(layout.entryPath, layout.sourceRoot)) {
+    return {
+      ok: false,
+      diagnostics: [
+        e5105EntryOutsideSourceRoot({
+          entryPath: layout.entryPath,
+          sourceRoot: layout.sourceRoot
+        })
+      ]
+    }
+  }
+  return { ok: true }
+}
+
+/**
+ * @param {{ outDir: string, sourceRoot: string }} layout — из {@link resolveCompileLayout}
+ * @param {string} sailPath — абсолютный или нормализуемый путь к `.sail`
+ * @returns {{ ok: true, path: string } | { ok: false, diagnostic: { code: string, message: string } }}
+ */
+export function sailModuleToOutputJsPath (layout, sailPath) {
+  const S = path.normalize(path.resolve(sailPath))
+  if (!isPathInsideSourceRoot(S, layout.sourceRoot)) {
+    return { ok: false, diagnostic: e5101SailOutsideSourceRoot(S) }
+  }
+  const rel = path.relative(layout.sourceRoot, S)
+  if (rel === '' || rel.split(path.sep).includes('..')) {
+    return { ok: false, diagnostic: e5101SailInvalidRelative(S) }
+  }
+  const { dir, name, ext } = path.parse(rel)
+  if (ext.toLowerCase() !== '.sail') {
+    return { ok: false, diagnostic: e5102SailExpectedExtension(S) }
+  }
+  const jsRel = path.join(dir, `${name}.js`)
+  return { ok: true, path: path.join(layout.outDir, jsRel) }
+}
+
+/**
+ * Выходной путь для проектного FFI `.js` (RFC-compile §9.1–9.2): зеркало относительного пути
+ * от `source-root` без смены расширения.
+ *
+ * @param {{ outDir: string, sourceRoot: string }} layout
+ * @param {string} jsPath — абсолютный или нормализуемый путь к `.js` под проектом
+ * @returns {{ ok: true, path: string } | { ok: false, diagnostic: { code: string, message: string } }}
+ */
+export function projectJsFileToOutputPath (layout, jsPath) {
+  const S = path.normalize(path.resolve(jsPath))
+  if (!isPathInsideSourceRoot(S, layout.sourceRoot)) {
+    return { ok: false, diagnostic: e5103FfiOutsideSourceRoot(S) }
+  }
+  const rel = path.relative(layout.sourceRoot, S)
+  if (rel === '' || rel.split(path.sep).includes('..')) {
+    return { ok: false, diagnostic: e5103FfiInvalidRelative(S) }
+  }
+  const ext = path.extname(rel)
+  if (ext.toLowerCase() !== '.js') {
+    return { ok: false, diagnostic: e5104FfiExpectedExtension(S) }
+  }
+  return { ok: true, path: path.join(layout.outDir, rel) }
+}