@algosail/lang 0.2.12 → 0.5.0

package/lib/ffi/extract-jsdoc-sail.js

@@ -0,0 +1,34 @@
+/**
+ * Извлечение текста Sail из JSDoc FFI (RFC-0.1 §10.1): JSDoc-блоки от открывающего до закрывающего
+ * ограничителя комментария, тег @sail, хвост после снятия префиксов строк со звёздочкой.
+ *
+ * Не полноценный JS-лексер: закрытие комментария — по первому вхождению пары символов star-slash.
+ */
+
+/**
+ * @param {string} sourceText
+ * @returns {string[]}
+ */
+export function extractSailFragmentsFromJs (sourceText) {
+  const out = []
+  let i = 0
+  while (i < sourceText.length) {
+    const open = sourceText.indexOf('/**', i)
+    if (open === -1) break
+    const close = sourceText.indexOf('*/', open + 3)
+    if (close === -1) break
+    const block = sourceText.slice(open + 3, close)
+    const tag = block.match(/@sail\b/)
+    if (tag && tag.index !== undefined) {
+      const afterTag = block.slice(tag.index + tag[0].length)
+      const lines = afterTag.split(/\r?\n/)
+      const cleaned = lines
+        .map(line => line.replace(/^\s*\* ?/, ''))
+        .join('\n')
+        .trim()
+      if (cleaned.length > 0) out.push(cleaned)
+    }
+    i = close + 2
+  }
+  return out
+}

package/lib/io-node/index.js

@@ -0,0 +1,4 @@
+export { createReadFileUtf8 } from './read-file.js'
+export { findPackageRoot } from './package-root.js'
+export { createResolvePackage } from './resolve-package.js'
+export { resolveSailNamesFromDisk } from './resolve-sail-names-from-disk.js'

package/lib/io-node/package-root.js

@@ -0,0 +1,18 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * @param {string} startAbsPath — абсолютный путь к файлу или каталогу
+ * @returns {string | null} — каталог с package.json или null
+ */
+export function findPackageRoot (startAbsPath) {
+  let current = path.dirname(startAbsPath)
+  for (;;) {
+    if (fs.existsSync(path.join(current, 'package.json'))) {
+      return path.resolve(current)
+    }
+    const parent = path.dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}

package/lib/io-node/read-file.js

@@ -0,0 +1,12 @@
+import fs from 'node:fs'
+
+/** @returns {(absPath: string) => string | null} */
+export function createReadFileUtf8 () {
+  return (absPath) => {
+    try {
+      return fs.readFileSync(absPath, 'utf8')
+    } catch {
+      return null
+    }
+  }
+}

package/lib/io-node/resolve-package.js

@@ -0,0 +1,24 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { findPackageRoot } from './package-root.js'
+
+/**
+ * @param {{ projectRoot?: string }} [options]
+ * @returns {(spec: string, fromPath: string) => string | null}
+ */
+export function createResolvePackage (options) {
+  const fixedRoot =
+    options?.projectRoot != null ? path.resolve(options.projectRoot) : null
+
+  return (spec, fromPath) => {
+    const root = fixedRoot ?? findPackageRoot(fromPath)
+    if (root === null) return null
+    try {
+      const req = createRequire(path.join(root, 'package.json'))
+      const resolved = req.resolve(spec, { paths: [path.dirname(fromPath)] })
+      return path.normalize(resolved)
+    } catch {
+      return null
+    }
+  }
+}

package/lib/io-node/resolve-sail-names-from-disk.js

@@ -0,0 +1,21 @@
+import path from 'node:path'
+import { resolveSailNames } from '../names/resolve-sail.js'
+import { createReadFileUtf8 } from './read-file.js'
+import { createResolvePackage } from './resolve-package.js'
+
+/**
+ * @param {{ entryPath: string, projectRoot?: string, withSnapshots?: boolean }} opts
+ */
+export function resolveSailNamesFromDisk (opts) {
+  const { entryPath, projectRoot, ...rest } = opts
+  const readFile = createReadFileUtf8()
+  const resolvePackage = createResolvePackage(
+    projectRoot != null ? { projectRoot } : undefined
+  )
+  return resolveSailNames({
+    entryPath: path.resolve(entryPath),
+    readFile,
+    resolvePackage,
+    ...rest
+  })
+}

package/lib/ir/assert-json-serializable.js

@@ -0,0 +1,30 @@
+/**
+ * Проверка, что значение без потерь уйдёт в JSON (для отладки и тестов IR wire).
+ *
+ * @param {unknown} value
+ * @param {string} [path]
+ */
+export function assertJsonSerializable (value, path = 'root') {
+  if (value === undefined) {
+    throw new Error(`IR JSON: недопустимо undefined в ${path}`)
+  }
+  const t = typeof value
+  if (t === 'function' || t === 'symbol') {
+    throw new Error(`IR JSON: недопустимый тип в ${path}`)
+  }
+  if (value === null || t === 'string' || t === 'number' || t === 'boolean') {
+    return
+  }
+  if (value instanceof Map || value instanceof WeakMap) {
+    throw new Error(`IR JSON: Map/WeakMap недопустимы в ${path}`)
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => assertJsonSerializable(item, `${path}[${i}]`))
+    return
+  }
+  if (t === 'object') {
+    for (const k of Object.keys(value)) {
+      assertJsonSerializable(/** @type {Record<string, unknown>} */ (value)[k], `${path}.${k}`)
+    }
+  }
+}

package/lib/ir/attach-call-effects.js

@@ -0,0 +1,108 @@
+/**
+ * L4 фаза 5: эффекты +Async / +Fail на wire IR (RFC-IR section 6).
+ * Данные берутся из `env.callSiteEffectMarks` (L3 этап 7) без повторного анализа эффектов.
+ *
+ * На узлах шагов (и вложенных `Quotation.steps`) опционально:
+ * - **`calleeAsync`**: маркер L3 «ожидать на codegen»; при поглощении `-Async` у вызывающего может отсутствовать (вариант B), тогда `await` решается по сигнатуре callee в L5.
+ * - **`calleeMayFail`**: у вызываемого +Fail (опционально для инструментов, RFC-IR §6.2).
+ *
+ * Сопоставление: `span.start` wire-узла (как в {@link lower-body-steps.js}) с `span` маркера;
+ * плюс `kind` маркера и имя builtin/слова.
+ */
+
+/**
+ * @param {unknown} wireSpan из IR-узла
+ * @param {unknown} astSpan из маркера L3 (тот же объект, что у шага парсера)
+ * @returns {boolean}
+ */
+function spanStartEqual (wireSpan, astSpan) {
+  if (
+    wireSpan == null ||
+    astSpan == null ||
+    typeof wireSpan !== 'object' ||
+    typeof astSpan !== 'object'
+  ) {
+    return false
+  }
+  const w = /** @type {{ start?: { offset?: number, line?: number, column?: number } }} */ (
+    wireSpan
+  )
+  const a = /** @type {{ start?: { offset?: number, line?: number, column?: number } }} */ (
+    astSpan
+  )
+  const ws = w.start
+  const as = a.start
+  if (ws == null || as == null) return false
+  return (
+    ws.offset === as.offset &&
+    ws.line === as.line &&
+    ws.column === as.column
+  )
+}
+
+/**
+ * @param {object} mark элемент `callSiteEffectMarks`
+ * @param {Record<string, unknown>} node узел `irSteps`
+ * @returns {boolean}
+ */
+function markMatchesNode (mark, node) {
+  if (!spanStartEqual(node.span, mark.span)) return false
+  const kind = mark.kind
+  switch (kind) {
+    case 'word_ref':
+      return (
+        node.kind === 'Word' &&
+        node.ref === 'local' &&
+        node.name === mark.name
+      )
+    case 'module_word_ref':
+      return (
+        node.kind === 'Word' &&
+        node.ref === 'qualified' &&
+        node.module === mark.module &&
+        node.word === mark.word
+      )
+    case 'call':
+      return node.kind === 'Builtin' && node.name === 'call'
+    case 'builtin_quote':
+      return node.kind === 'Builtin' && node.name === mark.builtin
+    default:
+      return false
+  }
+}
+
+/**
+ * Прикрепляет к узлам `irSteps` поля `calleeAsync` / `calleeMayFail` по отфильтрованным маркерам.
+ *
+ * @param {Record<string, unknown>[]} irSteps
+ * @param {object[]} marks `env.callSiteEffectMarks`, уже отфильтрованные по `modulePath` и `callerWord`
+ */
+export function attachCallSiteEffectMarksToIrSteps (irSteps, marks) {
+  if (!Array.isArray(irSteps) || !Array.isArray(marks) || marks.length === 0) {
+    return
+  }
+
+  /**
+   * @param {Record<string, unknown>[]} steps
+   */
+  function walk (steps) {
+    for (const raw of steps) {
+      if (raw == null || typeof raw !== 'object') continue
+      const node = /** @type {Record<string, unknown>} */ (raw)
+      const matching = marks.filter((m) => markMatchesNode(m, node))
+      if (matching.length > 0) {
+        if (matching.some((m) => m.calleeAsync === true)) {
+          node.calleeAsync = true
+        }
+        if (matching.some((m) => m.calleeMayFail === true)) {
+          node.calleeMayFail = true
+        }
+      }
+      if (node.kind === 'Quotation' && Array.isArray(node.steps)) {
+        walk(/** @type {Record<string, unknown>[]} */ (node.steps))
+      }
+    }
+  }
+
+  walk(irSteps)
+}