@algosail/lang 0.2.12 → 0.5.0

package/lib/ir/build-module-ir.js

@@ -0,0 +1,290 @@
+/**
+ * L4: каркас `module` из L2/L3 + wire-шаги тела (RFC-IR-0.1).
+ * `words[].irSteps` — узлы section 5; на них же (фаза 3) копируются `preTypes`/`postTypes` из `stackSteps`;
+ * фаза 5: `asyncDefinition`/`mayFail` на записи слова, `calleeAsync`/`calleeMayFail` на узлах вызова (RFC-IR §6);
+ * фаза 6: `imports[].resolvedPath`, на `Word` qualified — `resolvedModulePath` (RFC-IR §7, [module-metadata.js](./module-metadata.js)).
+ */
+import path from 'node:path'
+import { attachCallSiteEffectMarksToIrSteps } from './attach-call-effects.js'
+import {
+  attachResolvedModulePathToQualifiedWords,
+  enrichImportsWithResolvedPaths
+} from './module-metadata.js'
+import { lookupWordSignatureIr } from '../typecheck/check-word-body.js'
+import { lowerBodySteps } from './lower-body-steps.js'
+import { attachStackTypesToIrSteps } from './stitch-types.js'
+import { bindValueBindingsForIrSteps } from './bind-values.js'
+import { createSerializedIrDocument } from './serialize.js'
+
+/**
+ * @typedef {import('../typecheck/build-type-env.js').TypecheckEnv} TypecheckEnv
+ */
+
+/**
+ * @param {object | null | undefined} t
+ * @returns {unknown}
+ */
+function irTypeSlotToWire (t) {
+  if (t == null || typeof t !== 'object') return t
+  switch (t.kind) {
+    case 'prim':
+      return { kind: 'prim', name: t.name }
+    case 'tvar':
+      return { kind: 'tvar', name: t.name }
+    case 'stack_label':
+      return { kind: 'stack_label', name: t.name }
+    case 'opaque':
+      return { kind: 'opaque', name: t.name }
+    case 'app':
+      return {
+        kind: 'app',
+        ctor: t.ctor,
+        args: (t.args ?? []).map(irTypeSlotToWire)
+      }
+    case 'mod_adt':
+      return { kind: 'mod_adt', module: t.module, type: t.type }
+    case 'adt':
+      return { kind: 'adt', path: t.path, type: t.type }
+    case 'quote':
+      return { kind: 'quote', inner: normalizedSigToWire(t.inner) }
+    case 'named_quote':
+      return {
+        kind: 'named_quote',
+        prefix: t.prefix,
+        inner: normalizedSigToWire(t.inner)
+      }
+    default:
+      return { kind: String(t.kind ?? 'unknown') }
+  }
+}
+
+/**
+ * @param {import('../typecheck/normalize-sig.js').NormalizedSignature} sig
+ */
+function normalizedSigToWire (sig) {
+  if (!sig || typeof sig !== 'object') return sig
+  const out = {
+    left: (sig.left ?? []).map(irTypeSlotToWire),
+    right: (sig.right ?? []).map(irTypeSlotToWire),
+    effectsAdd: (sig.effectsAdd ?? []).map((e) => ({
+      kind: e.kind,
+      name: e.name,
+      side: e.side
+    })),
+    effectsRemove: (sig.effectsRemove ?? []).map((e) => ({
+      kind: e.kind,
+      name: e.name,
+      side: e.side
+    }))
+  }
+  if (sig.adtEliminator != null) {
+    out.adtEliminator = sig.adtEliminator
+  }
+  return out
+}
+
+/**
+ * @param {{ steps: object[], nestedByParentStep: Map<number, object> }} record
+ * @returns {object}
+ */
+function stackSnapshotRecordToWire (record) {
+  const steps = []
+  const rawSteps = record.steps ?? []
+  for (let i = 0; i < rawSteps.length; i++) {
+    const s = rawSteps[i]
+    if (s == null || typeof s !== 'object') {
+      steps.push(null)
+      continue
+    }
+    const stepOut = {
+      preTypes: (s.pre ?? []).map(irTypeSlotToWire)
+    }
+    if (s.post != null) {
+      stepOut.postTypes = s.post.map(irTypeSlotToWire)
+    }
+    steps.push(stepOut)
+  }
+  /** @type {{ parentStepIndex: number, record: object }[]} */
+  const nested = []
+  if (record.nestedByParentStep instanceof Map) {
+    for (const [parentStepIndex, inner] of record.nestedByParentStep) {
+      nested.push({
+        parentStepIndex,
+        record: stackSnapshotRecordToWire(inner)
+      })
+    }
+  }
+  const out = { steps }
+  if (nested.length > 0) {
+    out.nestedByParentStep = nested
+  }
+  return out
+}
+
+/**
+ * @param {object} item import AST item
+ */
+function importItemToWire (item) {
+  const w = {
+    module: item.module,
+    path: item.path
+  }
+  if (item.bracket) {
+    w.bracket = {
+      words: [...(item.bracket.words ?? [])],
+      types: [...(item.bracket.types ?? [])]
+    }
+  }
+  return w
+}
+
+/**
+ * @param {TypecheckEnv} env
+ * @param {string} modulePath
+ * @param {{
+ *   moduleStatus?: 'ok' | 'error'
+ *   valueBindings?: boolean
+ *   valueBindingsStrict?: boolean
+ * }} [options] при `moduleStatus` дублирует итог L3 в payload (корень документа — `meta.status` в {@link createSerializedIrDocument}).
+ * При `valueBindings: true` после фазы 3 заполняется `irSteps[*].valueBindings` (RFC-IR §4).
+ * @returns {import('./serialize.js').IrModulePayload}
+ */
+export function buildModuleIr (env, modulePath, options = {}) {
+  const normPath = path.normalize(modulePath)
+  const snap = env.snapshots?.get(normPath)
+  const scope = env.scopeByPath?.get(normPath)
+  const wordsMap = env.wordDeclByPath?.get(normPath)
+
+  /** @type {import('./serialize.js').IrModulePayload} */
+  const payload = {
+    path: normPath,
+    imports: [],
+    exportWords: [],
+    exportTypes: [],
+    adts: [],
+    words: []
+  }
+  if (options.moduleStatus != null) {
+    payload.status = options.moduleStatus
+  }
+
+  if (snap?.ok && Array.isArray(snap.items)) {
+    for (const it of snap.items) {
+      if (it.kind === 'import') {
+        payload.imports.push(importItemToWire(it))
+      }
+    }
+  }
+  enrichImportsWithResolvedPaths(payload.imports, snap, scope)
+
+  if (scope) {
+    payload.exportWords = Array.from(scope.exportWords ?? []).sort()
+    payload.exportTypes = Array.from(scope.exportTypes ?? []).sort()
+  }
+
+  const adtMap = env.adtByPath?.get(normPath)
+  if (adtMap instanceof Map) {
+    const names = [...adtMap.keys()].sort()
+    for (const name of names) {
+      const e = adtMap.get(name)
+      if (!e) continue
+      payload.adts.push({
+        kind: e.kind,
+        name: e.name,
+        typeParams: [...(e.typeParams ?? [])]
+      })
+    }
+  }
+
+  const sigsForPath = env.sigIrByPath?.get(normPath)
+  const snapsForPath = env.stackSnapshotsByPath?.get(normPath)
+
+  if (wordsMap instanceof Map) {
+    const names = [...wordsMap.keys()].sort()
+    for (const name of names) {
+      const word = wordsMap.get(name)
+      const exported = scope?.exportWords?.has(name) ?? false
+      const sigAvailable = sigsForPath instanceof Map && sigsForPath.has(name)
+      /** @type {Record<string, unknown>} */
+      const entry = {
+        name,
+        exported,
+        sigAvailable
+      }
+      if (sigAvailable) {
+        const sig = sigsForPath.get(name)
+        entry.normalizedSig = normalizedSigToWire(sig)
+      }
+      const defFx = env.definitionEffectsByPath?.get(normPath)
+      const fx =
+        defFx instanceof Map ? defFx.get(name) : undefined
+      entry.asyncDefinition = fx?.asyncDefinition === true
+      entry.mayFail = fx?.mayFail === true
+      if (snapsForPath instanceof Map && snapsForPath.has(name)) {
+        entry.stackSteps = stackSnapshotRecordToWire(snapsForPath.get(name))
+      }
+      if (Array.isArray(word.body)) {
+        entry.irSteps = lowerBodySteps(normPath, name, word.body)
+        if (scope?.importMap instanceof Map) {
+          attachResolvedModulePathToQualifiedWords(
+            entry.irSteps,
+            scope.importMap
+          )
+        }
+        if (entry.stackSteps != null) {
+          attachStackTypesToIrSteps(entry.irSteps, entry.stackSteps)
+        }
+        const marks = env.callSiteEffectMarks ?? []
+        const marksForWord = marks.filter(
+          (m) => path.normalize(m.modulePath) === normPath && m.callerWord === name
+        )
+        attachCallSiteEffectMarksToIrSteps(entry.irSteps, marksForWord)
+        if (options.valueBindings === true && Array.isArray(entry.irSteps)) {
+          const entryStackIds = bindValueBindingsForIrSteps(entry.irSteps, {
+            wordName: name,
+            modulePath: normPath,
+            strict: options.valueBindingsStrict === true,
+            resolveLocalWordSig: (wn) =>
+              lookupWordSignatureIr(env, normPath, null, wn),
+            resolveQualifiedWordSig: (modAlias, w) =>
+              lookupWordSignatureIr(env, normPath, modAlias, w)
+          })
+          if (entryStackIds != null) {
+            entry.entryStackIds = entryStackIds
+          }
+        }
+      }
+      payload.words.push(entry)
+    }
+  }
+
+  return payload
+}
+
+/**
+ * @param {TypecheckEnv} env
+ * @param {string} modulePath
+ * @param {{
+ *   moduleStatus: 'ok' | 'error',
+ *   producer?: { name: string, version?: string },
+ *   sources?: { path?: string, uri?: string, sha256?: string }[],
+ *   valueBindings?: boolean,
+ *   valueBindingsStrict?: boolean
+ * }} opts
+ */
+export function buildSerializedIrDocumentFromEnv (env, modulePath, opts) {
+  const modulePayload = buildModuleIr(env, modulePath, {
+    moduleStatus: opts.moduleStatus,
+    valueBindings: opts.valueBindings === true,
+    valueBindingsStrict: opts.valueBindingsStrict === true
+  })
+  /** @type {{ status: 'ok' | 'error', producer?: object, sources?: object[] }} */
+  const meta = { status: opts.moduleStatus }
+  if (opts.producer != null) {
+    meta.producer = opts.producer
+  }
+  if (opts.sources != null) {
+    meta.sources = opts.sources
+  }
+  return createSerializedIrDocument(modulePayload, { meta })
+}

package/lib/ir/index.js

@@ -0,0 +1,31 @@
+/**
+ * L4: typed IR после lowering — [RFC-IR-0.1.md](../../../../RFC-IR-0.1.md).
+ *
+ * Входные данные: любой итог `typecheckSail` и `TypecheckEnv`
+ * (`ok: true` или частичный L3 при ошибках); статус модуля в IR (`meta.status`, опционально
+ * `module.status` в payload) задаёт вызывающий код — см. {@link buildModuleIr}.
+ */
+
+export { IR_SCHEMA_VERSION } from './schema-version.js'
+export { attachCallSiteEffectMarksToIrSteps } from './attach-call-effects.js'
+export {
+  attachResolvedModulePathToQualifiedWords,
+  enrichImportsWithResolvedPaths
+} from './module-metadata.js'
+export { assertJsonSerializable } from './assert-json-serializable.js'
+export { bindValueBindingsForIrSteps } from './bind-values.js'
+export { buildModuleIr, buildSerializedIrDocumentFromEnv } from './build-module-ir.js'
+export { lowerBodySteps, irBodyStepNodeId } from './lower-body-steps.js'
+export {
+  attachStackTypesToIrSteps,
+  verifyWireStackSnapshot,
+  wireStackSnapshotToRecord
+} from './stitch-types.js'
+export {
+  createSerializedIrDocument,
+  unwrapSerializedIrDocument,
+  unwrapSerializedIrDocumentFull,
+  stringifyIrDocument,
+  parseIrDocument,
+  parseIrDocumentFull
+} from './serialize.js'

package/lib/ir/lower-body-steps.js

@@ -0,0 +1,170 @@
+/**
+ * L4 фаза 2: `word.body` (AST) → wire-узлы RFC-IR section 5.
+ * Без стыковки с `stackSteps` (фаза 3). JSON-safe: только примитивы, массивы, plain objects.
+ */
+
+/**
+ * Стабильный id шага: `{modulePath}#{wordName}#{indexPath}`; `indexPath` — индексы через `.`
+ * (корень `0`, вложение `( … )` у шага `2`: `2.0`, `2.1`, …). Совместимо с [serialize.js](./serialize.js).
+ *
+ * @param {string} modulePath нормализованный путь модуля
+ * @param {string} wordName
+ * @param {number[]} indexPath
+ * @returns {string}
+ */
+export function irBodyStepNodeId (modulePath, wordName, indexPath) {
+  const tail = indexPath.length ? indexPath.join('.') : ''
+  return tail
+    ? `${modulePath}#${wordName}#${tail}`
+    : `${modulePath}#${wordName}#`
+}
+
+/**
+ * @param {{ start: object, end?: object } | null | undefined} span
+ * @returns {{ start: object, end?: object } | undefined}
+ */
+function spanToWire (span) {
+  if (span == null || typeof span !== 'object' || span.start == null) {
+    return undefined
+  }
+  const out = {
+    start: {
+      offset: span.start.offset,
+      line: span.start.line,
+      column: span.start.column
+    }
+  }
+  if (span.end != null) {
+    out.end = {
+      offset: span.end.offset,
+      line: span.end.line,
+      column: span.end.column
+    }
+  }
+  return out
+}
+
+/**
+ * @param {object} step AST word_step
+ * @param {string} modulePath
+ * @param {string} wordName
+ * @param {number[]} indexPath
+ * @returns {Record<string, unknown>}
+ */
+function lowerOneStep (step, modulePath, wordName, indexPath) {
+  const nodeId = irBodyStepNodeId(modulePath, wordName, indexPath)
+  const span = spanToWire(step.span)
+
+  switch (step.kind) {
+    case 'literal':
+      return {
+        kind: 'Literal',
+        nodeId,
+        litKind: step.litKind,
+        raw: step.raw,
+        span
+      }
+    case 'builtin':
+      return {
+        kind: 'Builtin',
+        nodeId,
+        name: step.name,
+        span
+      }
+    case 'word_ref':
+      return {
+        kind: 'Word',
+        nodeId,
+        ref: 'local',
+        name: step.name,
+        span
+      }
+    case 'module_word_ref':
+      return {
+        kind: 'Word',
+        nodeId,
+        ref: 'qualified',
+        module: step.module,
+        word: step.word,
+        span
+      }
+    case 'quotation': {
+      const inner = step.body ?? []
+      /** @type {Record<string, unknown>[]} */
+      const steps = []
+      for (let j = 0; j < inner.length; j++) {
+        steps.push(
+          lowerOneStep(inner[j], modulePath, wordName, [...indexPath, j])
+        )
+      }
+      return {
+        kind: 'Quotation',
+        nodeId,
+        span,
+        steps
+      }
+    }
+    case 'slot_read':
+      return {
+        kind: 'Slot',
+        nodeId,
+        direction: 'read',
+        slotName: step.name,
+        span
+      }
+    case 'slot_write':
+      return {
+        kind: 'Slot',
+        nodeId,
+        direction: 'write',
+        slotName: step.name,
+        span
+      }
+    case 'list_literal': {
+      const elements = step.elements ?? []
+      /** @type {Record<string, unknown>[]} */
+      const wireElements = []
+      for (let j = 0; j < elements.length; j++) {
+        const el = elements[j]
+        wireElements.push({
+          kind: 'Literal',
+          nodeId: `${nodeId}.e${j}`,
+          litKind: el.litKind,
+          raw: el.raw,
+          span: spanToWire(el.span)
+        })
+      }
+      return {
+        kind: 'ListLiteral',
+        nodeId,
+        span,
+        elements: wireElements
+      }
+    }
+    default:
+      return {
+        kind: 'Unknown',
+        nodeId,
+        astKind: String(step.kind ?? 'unknown'),
+        span
+      }
+  }
+}
+
+/**
+ * @param {string} modulePath нормализованный путь (как ключи `TypecheckEnv`)
+ * @param {string} wordName
+ * @param {object[]} bodySteps `word.body` из AST
+ * @returns {Record<string, unknown>[]}
+ */
+export function lowerBodySteps (modulePath, wordName, bodySteps) {
+  if (!Array.isArray(bodySteps)) {
+    return []
+  }
+  /** @type {Record<string, unknown>[]} */
+  const out = []
+  for (let i = 0; i < bodySteps.length; i++) {
+    out.push(lowerOneStep(bodySteps[i], modulePath, wordName, [i]))
+  }
+  return out
+}

package/lib/ir/module-metadata.js

@@ -0,0 +1,65 @@
+/**
+ * L4 фаза 6: метаданные модуля (RFC-IR section 7).
+ * Резолв путей импорта и квалифицированных вызовов из `scopeByPath` (тот же граф, что после `resolveSailNames`), без повторного `resolveImportPath`.
+ *
+ * - **`imports[].resolvedPath`**: нормализованный путь модуля-зависимости (`dep.path` из `importMap.get(алиас)`).
+ * - **`Word` с `ref === 'qualified'`**: опционально **`resolvedModulePath`** — тот же путь для алиаса `module`.
+ */
+
+import path from 'node:path'
+
+/**
+ * @param {Record<string, unknown>[]} imports wire-записи в порядке импортов в снимке
+ * @param {{ ok?: boolean, items?: object[] } | null | undefined} snap снимок текущего модуля
+ * @param {{ importMap?: Map<string, { path?: string }> } | null | undefined} scope из `scopeByPath`
+ */
+export function enrichImportsWithResolvedPaths (imports, snap, scope) {
+  if (!Array.isArray(imports) || imports.length === 0) return
+  const im = scope?.importMap
+  if (!(im instanceof Map)) return
+  if (!snap?.ok || !Array.isArray(snap.items)) return
+  let idx = 0
+  for (const item of snap.items) {
+    if (item.kind !== 'import') continue
+    const wire = imports[idx]
+    if (wire == null || typeof wire !== 'object') break
+    const dep = im.get(item.module)
+    if (dep != null && typeof dep.path === 'string' && dep.path.length > 0) {
+      wire.resolvedPath = path.normalize(dep.path)
+    }
+    idx++
+  }
+}
+
+/**
+ * @param {Record<string, unknown>[]} irSteps
+ * @param {Map<string, { path?: string }>} importMap
+ */
+export function attachResolvedModulePathToQualifiedWords (irSteps, importMap) {
+  if (!Array.isArray(irSteps) || !(importMap instanceof Map)) 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)
+      if (
+        node.kind === 'Word' &&
+        node.ref === 'qualified' &&
+        typeof node.module === 'string'
+      ) {
+        const dep = importMap.get(node.module)
+        if (dep != null && typeof dep.path === 'string' && dep.path.length > 0) {
+          node.resolvedModulePath = path.normalize(dep.path)
+        }
+      }
+      if (node.kind === 'Quotation' && Array.isArray(node.steps)) {
+        walk(/** @type {Record<string, unknown>[]} */ (node.steps))
+      }
+    }
+  }
+
+  walk(irSteps)
+}

package/lib/ir/schema-version.js

@@ -0,0 +1,15 @@
+/**
+ * Версия логической схемы wire-формата IR (RFC-IR-0.1 §8).
+ * Инкремент при ломающих изменениях обязательных полей корня или семантики `module`.
+ *
+ * Опциональные ключи корня (`views`, `meta`) не требуют bump, пока читатели совместимы
+ * с тем же значением строки версии.
+ *
+ * 0.1.1 — опциональное `module.words[].irSteps` (фаза 2, RFC-IR section 5 wire).
+ * 0.1.2 — `stackSteps.steps[]` с выравниванием по индексу тела (`null` при отсутствии снимка);
+ *   `irSteps[*].preTypes`/`postTypes` после фазы 3 ([stitch-types.js](./stitch-types.js)).
+ * 0.1.3 — опционально `irSteps[*].valueBindings` (фаза 4, RFC-IR section 4, [bind-values.js](./bind-values.js)).
+ * 0.1.4 — `module.words[].asyncDefinition`/`mayFail` и на шагах `calleeAsync`/`calleeMayFail` (фаза 5, RFC-IR §6, [attach-call-effects.js](./attach-call-effects.js)).
+ * 0.1.5 — `module.imports[].resolvedPath`, на `Word` qualified — `resolvedModulePath` (фаза 6, RFC-IR §7, [module-metadata.js](./module-metadata.js)).
+ */
+export const IR_SCHEMA_VERSION = '0.1.5'