@algosail/lang 0.2.12 → 0.5.0

package/bin/sail.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../cli/run-cli.js'
+
+await main()

package/cli/run-cli.js

@@ -0,0 +1,176 @@
+/**
+ * CLI @algosail/lang: подкоманды typecheck и compile (RFC-compile §9.1).
+ */
+import { parseArgs } from 'node:util'
+import path from 'node:path'
+import {
+  compileSailToOutDir,
+  createReadFileUtf8,
+  createResolvePackage,
+  findPackageRoot,
+  typecheckSail
+} from '../index.js'
+
+/**
+ * @param {object} d
+ * @returns {string}
+ */
+export function formatDiagnosticLine (d) {
+  if (d == null || typeof d !== 'object') return String(d)
+  const code = d.code != null ? String(d.code) : ''
+  const msg = d.message != null ? String(d.message) : ''
+  const bits = [code, msg].filter(Boolean)
+  if (typeof d.path === 'string' && d.path.length > 0) bits.push(`path ${d.path}`)
+  if (d.line != null) bits.push(`line ${d.line}`)
+  if (d.column != null) bits.push(`col ${d.column}`)
+  return bits.join(' — ')
+}
+
+/**
+ * @param {string} entryPath
+ * @param {string | undefined} projectRootFlag
+ * @returns {(spec: string, fromPath: string) => string | null}
+ */
+export function resolvePackageForCli (entryPath, projectRootFlag) {
+  const resolvedFlag =
+    projectRootFlag != null && projectRootFlag !== ''
+      ? path.resolve(projectRootFlag)
+      : null
+  const root = resolvedFlag ?? findPackageRoot(entryPath)
+  if (root != null) {
+    return createResolvePackage({ projectRoot: root })
+  }
+  return createResolvePackage()
+}
+
+function printUsage () {
+  process.stderr.write(`Usage:
+  sail-lang typecheck [--project-root <dir>] <entry.sail>
+  sail-lang compile [--out-dir|-o <dir>] [--source-root <dir>] [--project-root <dir>] <entry.sail>
+
+Options:
+  --project-root   Корень package.json для resolve npm (иначе ищется вверх от entry)
+  --source-root    RFC-compile §9.1 (по умолчанию dirname(entry))
+  -h, --help       Справка
+
+Диагностики печатаются в stderr; код выхода 0 при успехе, 1 при ошибке.
+`)
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ stdout?: NodeJS.WriteStream, stderr?: NodeJS.WriteStream }} [io]
+ * @returns {Promise<number>} exit code
+ */
+export async function runCli (argv, io = {}) {
+  const out = io.stdout ?? process.stdout
+  const err = io.stderr ?? process.stderr
+
+  let tokens
+  try {
+    tokens = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      strict: true,
+      options: {
+        help: { type: 'boolean', short: 'h' },
+        'project-root': { type: 'string' },
+        'out-dir': { type: 'string', short: 'o' },
+        'source-root': { type: 'string' }
+      }
+    })
+  } catch (e) {
+    err.write(String(e?.message ?? e) + '\n')
+    printUsage()
+    return 1
+  }
+
+  const { values, positionals } = tokens
+
+  if (values.help === true) {
+    printUsage()
+    return 0
+  }
+  if (positionals.length === 0) {
+    printUsage()
+    return 1
+  }
+
+  const cmd = positionals[0]
+  const entryRaw = positionals[1]
+
+  if (entryRaw == null || entryRaw === '') {
+    err.write('Missing <entry.sail>\n')
+    printUsage()
+    return 1
+  }
+
+  const entryPath = path.resolve(process.cwd(), entryRaw)
+  const readFile = createReadFileUtf8()
+  const resolvePackage = resolvePackageForCli(
+    entryPath,
+    values['project-root']
+  )
+
+  if (cmd === 'typecheck') {
+    if (positionals.length > 2) {
+      err.write('Too many arguments for typecheck\n')
+      return 1
+    }
+    const r = typecheckSail({ entryPath, readFile, resolvePackage })
+    if (!r.ok) {
+      for (const d of r.diagnostics ?? []) {
+        err.write(formatDiagnosticLine(d) + '\n')
+      }
+      return 1
+    }
+    out.write('ok\n')
+    return 0
+  }
+
+  if (cmd === 'compile') {
+    if (positionals.length > 2) {
+      err.write('Too many arguments for compile\n')
+      return 1
+    }
+    const outDir = values['out-dir']
+    if (outDir == null || outDir === '') {
+      err.write('compile requires --out-dir (-o)\n')
+      printUsage()
+      return 1
+    }
+    const outDirAbs = path.resolve(process.cwd(), outDir)
+    const sourceRoot =
+      values['source-root'] != null && values['source-root'] !== ''
+        ? path.resolve(process.cwd(), values['source-root'])
+        : undefined
+
+    const r = await compileSailToOutDir({
+      entryPath,
+      outDir: outDirAbs,
+      sourceRoot,
+      readFile,
+      resolvePackage
+    })
+    if (!r.ok) {
+      for (const d of r.diagnostics ?? []) {
+        err.write(formatDiagnosticLine(d) + '\n')
+      }
+      return 1
+    }
+    for (const p of r.emitted ?? []) {
+      out.write(`${p}\n`)
+    }
+    return 0
+  }
+
+  err.write(`Unknown command: ${cmd}\n`)
+  printUsage()
+  return 1
+}
+
+/** Запуск из bin: динамический import index по file URL (cwd может быть любым). */
+export async function main () {
+  const code = await runCli(process.argv.slice(2))
+  process.exitCode = code
+}

package/index.js

@@ -1,2 +1,11 @@
-export { typecheck } from '@algosail/typecheck'
-export { createParser } from '@algosail/parser'
+export { parseSource } from './lib/parse/index.js'
+export { isBuiltinWord, BUILTIN_WORDS } from './lib/parse/builtins-set.js'
+export { resolveSailNames } from './lib/names/index.js'
+export { typecheckSail } from './lib/typecheck/index.js'
+export { compileSailToOutDir } from './lib/codegen/index.js'
+export {
+  createReadFileUtf8,
+  createResolvePackage,
+  findPackageRoot,
+  resolveSailNamesFromDisk
+} from './lib/io-node/index.js'

package/lib/codegen/README.md

@@ -0,0 +1,230 @@
+# L5 Codegen (`lang/lib/codegen`)
+
+Цель каталога: **полная** реализация генерации JavaScript (уровень **L5** по [RFC-conformance-0.1.md](../../../RFC-conformance-0.1.md)) в профиле lowering v0.1 [RFC-compile-0.1.md](../../../RFC-compile-0.1.md).
+
+Нормативные документы (при конфликте с кодом побеждает RFC, см. правила репозитория):
+
+| Документ | Роль для codegen |
+|----------|------------------|
+| [RFC-compile-0.1.md](../../../RFC-compile-0.1.md) | Пайплайн §4, профиль §1.1, стек §6, слова/quotation/builtins §7, ADT/литералы §8, ESM §9, `+Async` §10, `@sail` §11, диагностики §12, цель ES2025 §13 |
+| [RFC-IR-0.1.md](../../../RFC-IR-0.1.md) | Входная модель IR; для пути codegen — полнота §§2–7 при `ok`, обязательно **привязки значений §4** там, где нужен JS (согласовано с RFC-compile §5–§6.2) |
+| [RFC-0.1.md](../../../RFC-0.1.md) | Семантика, FFI §10.1, модули §4.2 |
+| [RFC-builtins-0.1.md](../../../RFC-builtins-0.1.md) | Семантика `builtin_word` |
+| [RFC-typecheck-0.1.md](../../../RFC-typecheck-0.1.md) | Уже отработанные инварианты до IR; codegen их не пересчитывает |
+| [RFC-conformance-0.1.md](../../../RFC-conformance-0.1.md) | Эталонные кейсы L5 в `conformance/` и поля манифеста §5 |
+
+**Граница до L5:** codegen **не** запускается, пока агрегатный итог L3 (и статус IR для рабочего набора модулей) не **`ok`** (RFC-compile §4, RFC-IR §1.1).
+
+**Вне нормы v0.1** (не блокируют заявление L5 по RFC-compile): bundler, минификация, обязательные source maps, TypeScript — см. RFC-compile §2.
+
+---
+
+## Входные данные реализации
+
+- Успешный проход **Parse → Names → Typecheck** для замыкания модулей от `entry`.
+- Построение IR: `buildModuleIr` / `buildSerializedIrDocumentFromEnv` из [lang/lib/ir/](../ir/) с **`valueBindings: true`** на пути «компиляция → JS».
+- Параметры компиляции (нормативная модель): **`entry`**, **`out-dir`**, опционально **`source-root`** (RFC-compile §9.2).
+
+---
+
+## Предлагаемая раскладка модулей (после начала кодирования)
+
+Имена ориентировочные; группировать по сущности, без «один экспорт — один файл» без нужды (см. `AGENTS.md`).
+
+| Файл / область | Назначение |
+|----------------|------------|
+| `index.js` | Публичный API (например `compileSailToOutDir`, типы опций) |
+| `compile-graph.js` | Обход графа модулей от `entry`, порядок эмиссии, вызов IR + emit на модуль |
+| `emit-module.js` | Один `.sail` → один ESM: импорты, тела слов, экспорты |
+| `emit-body.js` | Обход `irSteps` + `valueBindings`: виртуальный стек → выражения / последовательность операторов; ветвление quotation: инлайн при `call`, `const qN = () => …` в точке передачи как значение (RFC-compile §6.3) |
+| `emit-builtin.js` | Отображение узлов builtin в JS (инлайн или вызовы рантайма — по стратегии) |
+| `emit-adt.js` | Тела автоген-слов ADT (RFC-0.1 §7): sum/product, eliminator по `arguments` |
+| `emit-async.js` | `async` / `await` по `asyncDefinition`, `calleeAsync` (RFC-compile §10) |
+| `esm-imports.js` | Построение статических `import` и спецификаторов §9.2 |
+| `out-layout.js` | Пути `O(S)`, копирование FFI `.js`, зеркало дерева (§9.1) |
+| `emit-jsdoc-sail.js` | JSDoc с `@sail` и печать Sail-фрагментов (ADT из AST, сигнатуры слова из AST или wire IR); контракт как у FFI ([extract-jsdoc-sail.js](../ffi/extract-jsdoc-sail.js)) |
+| `codegen-diagnostics.js` | Реестр кодов **E51xx**–**E53xx** и фабрики сообщений (поле `path` для привязки к файлу; RFC-compile §12) |
+
+Тесты: `lang/test/codegen/**/*.test.js` (brittle), плюс расширение conformance-раннера под поля `requireJs` / ожидаемый JS по [RFC-conformance-0.1.md](../../../RFC-conformance-0.1.md) §5.
+
+---
+
+## Этапы реализации (полная программа)
+
+Каждый этап завершается **критерием приёмки**: brittle-тесты и/или кейсы conformance, **без** ослабления профиля RFC-compile §1.1.
+
+### Этап 0 — Каркас драйвера и контракт вызова
+
+**Цель:** единая точка входа «после L3»: проверка `ok`, отказ с диагностиками без записи JS; при `ok` — передача управления графу модулей.
+
+**RFC:** RFC-compile §4, RFC-IR §1.1.
+
+**Результат:** функция верхнего уровня (например в `index.js` или `compile-graph.js`), принимающая `entry`, `out-dir`, `source-root`, колбэки чтения файлов; явное ветвление «не ok → только diagnostics».
+
+**Критерий приёмки:** тест: при намеренной ошибке L3 — ни одного `.js` в `out-dir`; при успешном минимальном модуле — допускается заглушка «пустой или минимальный ESM» до этапа 3.
+
+---
+
+### Этап 1 — Ядро тела слова: `irSteps` + `valueBindings`
+
+**Цель:** из IR узлов §5 и привязок §4 строить эквивалент потока значений в JS **без** массива как модели стека (RFC-compile §1.1 п.4, §6.2).
+
+**RFC:** RFC-IR §§3–5, RFC-compile §6–§7 (фрагменты без модуля).
+
+**Результат:** для одного слова (или внутреннего фрагмента) генерация последовательности присваиваний / выражений, корректная перестановка идентичностей для shuffle-слов через `argIds` / `resultIds`.
+
+**Подэтапы (логические):**
+
+1. Литералы и простые builtin с фиксированной семантикой.
+2. Вызов локального `@word` (тот же модуль) как функции с аргументами в порядке RFC-0.1 §10.1 (вершина — последний параметр).
+3. Остальные виды узлов IR по мере необходимости (включая `Slot` и т.д. по RFC-IR §5).
+
+**Критерий приёмки:** тесты на цепочки вроде `dup` / `swap` / `drop` + вызов; снимок или assert на отсутствие «единого стек-массива» в сгенерированном тексте (эвристика или структурная проверка AST выхода — на усмотрение).
+
+---
+
+### Этап 2 — Quotation: `call` и значения первого класса
+
+**Цель:** согласовать эмиссию quotation с профилем v0.1 (RFC-compile §1.1 п.3, **§6.3**): отдельная JS-функция для тела quotation **не** появляется «сама по себе» при проходе по IR.
+
+**Правила:**
+
+1. До **`call`** и до шага, где quotation нужна как **значение** для слова/FFI (в т.ч. со стека), **не** эмитить лишние обёртки-функции.
+2. На **`call`** — тело соответствующей quotation **инлайнится** в текущую генерируемую функцию слова (тот же контур, что и остальные шаги тела), без обязательного вызова отдельной функции только ради quotation.
+3. Когда quotation **передаётся** как аргумент (функция высшего порядка) — в точке использования эмитится **стрелочная функция**; **рекомендуется** именованная привязка `const qN = () => { … }`, чтобы в будущем (вне скоупа текущей реализации) можно было добавить метапрограммирование / методы на представлении quotation без смены общей схемы codegen.
+
+**RFC:** RFC-IR узлы `quote` / `named_quote`; RFC-compile §6.3, §7 п.2.
+
+**Критерий приёмки:** сценарии только с `call` — в сгенерированном тексте нет обязательной отдельной функции на каждую литеральную quotation; сценарий передачи quotation в слово высшей порядки — есть локальная функция (стрелочная) в точке передачи; исполнение под Node даёт семантику, эквивалентную ядру.
+
+---
+
+### Этап 3 — Оболочка одного ESM-файла
+
+**Цель:** один модуль `.sail` → один `.js` с статическими `import` и `export` (RFC-compile §9 п.1–3, §1.1 п.2).
+
+**RFC:** RFC-IR §7 (импорты с `resolvedPath` где есть), RFC-0.1 §4.2.
+
+**Результат:**
+
+- Верх файла: только статические `import` (без `import()` для sail-зависимостей).
+- Экспорт всех символов, которые модуль экспортирует по правилам Sail; внутренние хелперы без экспорта.
+
+**Критерий приёмки:** двухмодульный проект (entry + один импорт `.sail`), Node ESM разрешает модули; символы доступны снаружи согласно исходному экспорту.
+
+---
+
+### Этап 4 — Граф модулей и раскладка `out-dir`
+
+**Цель:** транзитивное замыкание от `entry`, зеркало путей, копирование проектных FFI `.js` (RFC-compile §9.1–§9.2).
+
+**RFC:** ацикличность sail→sail уже проверена на L2 (`E1112`).
+
+**Результат:**
+
+- Вычисление `O(S)` для каждого `.sail` и FFI `.js` в замыкании.
+- Относительные спецификаторы между артефактами под `out-dir` с `./` / `../` и суффиксом `.js`.
+- npm / bare спецификаторы в `import` как в исходном `path`, без копирования пакетов в `out-dir`.
+
+**Критерий приёмки:** интеграционный тест с вложенными каталогами + FFI-файлом; импорты разрешаются из `out-dir`.
+
+---
+
+### Этап 5 — `+Async` и `await`
+
+**Цель:** слова с `+Async` → `async function`; вызовы с `calleeAsync` → `await` (RFC-compile §10, маркировка IR RFC-IR §6).
+
+**Результат:** согласованность с типизацией (`E1310` уже до codegen); корректный возврат `Promise` / кортежа для нескольких выходов (§10 п.3–4).
+
+**Критерий приёмки:** тест на async-цепочку; отсутствие «висящих» `Promise` на стеке после `await`.
+
+---
+
+### Этап 6 — ADT, литералы, eliminator-ы
+
+**Цель:** конструкторы, распознаватели и автоген в соответствии с RFC-0.1 §7–§8 и RFC-compile §7–§8.
+
+**Результат:** согласованные runtime-формы; eliminator-ы не обязаны быть отдельными builtin-вызовами, если семантика совпадает (RFC-compile §7 п.4).
+
+**Реализация:** [emit-adt.js](emit-adt.js) (тела автоген-`function` по ADT); [emit-module.js](emit-module.js) — только используемые автогены без `export`, `~M/w` → `__adt_M__w`; [emit-body.js](emit-body.js) — `ListLiteral`, `Slot`, вызов sum-eliminator с префиксом стека; [bind-values.js](../ir/bind-values.js) — `ListLiteral`, исправление `slice(-0)` при `nIn===0`; list literal в [check-word-body.js](../typecheck/check-word-body.js).
+
+**Критерий приёмки:** [lang/test/codegen/emit-adt-stage6.test.js](../../test/codegen/emit-adt-stage6.test.js); `npm test` в `lang/`.
+
+---
+
+### Этап 7 — Полное покрытие builtins
+
+**Цель:** каждый `builtin_word` из RFC-builtins либо инлайнится, либо маппится на корректный JS с той же семантикой (RFC-compile §7 п.3).
+
+**Результат:** перестановки §4.1–4.2 — таблицы shuffle в [emit-body.js](emit-body.js) и [bind-values.js](../ir/bind-values.js); `call` — инлайн/invoke в [emit-body.js](emit-body.js); комбинаторы `dip`, `keep`, `bi`, `tri`, `spread`, `both` — [emit-builtin.js](emit-builtin.js) и согласованные `valueBindings` + `combinatorInlineMeta` в [bind-values.js](../ir/bind-values.js) (ветка `kind: 'inline'` из `quoteRegistry`, иначе `kind: 'invoke'` по типу `Quote` в `preTypes`, когда значение quotation пришло из вызова слова). Рекурсивный обход `+Async` / вариант B — [emit-body.js](emit-body.js) (`irStepsContainsCalleeAsync`, `irStepsCallsPropagatingAsyncCallee`) для вложенных шагов только у частей `kind: 'inline'`.
+
+**Критерий приёмки:** [lang/test/codegen/emit-builtins-stage7.test.js](../../test/codegen/emit-builtins-stage7.test.js); полный `npm test` в `lang/`; при новом `builtin_word` в RFC — `builtins-set.js`, `builtin-signatures.js`, при необходимости `bind-values.js`, shuffle-таблица или [emit-builtin.js](emit-builtin.js).
+
+---
+
+### Этап 8 — `@sail` в сгенерированном JS
+
+**Цель:** извлекаемый контракт для потребителей FFI (RFC-compile §11, RFC-0.1 §10.1).
+
+**Результат:** [emit-jsdoc-sail.js](emit-jsdoc-sail.js) строит JSDoc (префикс до `@sail` из `doc` AST, затем только Sail); [emit-module.js](emit-module.js) вставляет верхний блок с объявлениями экспортируемых `&` (порядок `items` снимка) сразу после `import` и перед ADT-autogen, и отдельный блок перед каждым `export function`. Внутренние `function` autogen без `@sail`. Сбой формирования блока: `E5206`. `+Async` в контракте слова согласован с `export async` (включая всплытие от async-callee по тому же правилу, что эмиттер тела).
+
+**Критерий приёмки:** [lang/test/codegen/emit-jsdoc-stage8.test.js](../../test/codegen/emit-jsdoc-stage8.test.js) (`extractSailFragmentsFromJs`, разбор фрагментов через `parseSource`); полный `npm test` в `lang/`.
+
+---
+
+### Этап 9 — Диагностики codegen и полировка
+
+**Цель:** ошибки конфигурации (`source-root`, выход за пределы дерева), невозможность эмиссии или копии FFI — с **стабильными кодами** и привязкой к путям где уместно (RFC-compile §12; span из парсера для codegen в v0.1 не обязателен).
+
+**Результат:** [codegen-diagnostics.js](codegen-diagnostics.js) — фабрики для **E5101**–**E5105** (раскладка путей и `entryPath` ⊂ `sourceRoot` в [out-layout.js](out-layout.js)), **E5201**–**E5206** ([emit-module.js](emit-module.js)), **E5301**–**E5302** ([compile-graph.js](compile-graph.js)). `E5301` только если в замыкании есть проектный FFI `.js` под `source-root` и не передан `readFile`. Эмиссия по графу — **best-effort**: при ошибке после части записей часть файлов в `out-dir` уже может существовать; до codegen по-прежнему «не ok L3 → без записи».
+
+**Критерий приёмки:** [lang/test/codegen/emit-diagnostics-stage9.test.js](../../test/codegen/emit-diagnostics-stage9.test.js); полный `npm test` в `lang/`.
+
+---
+
+### Этап 10 — Conformance L5 и регрессия
+
+**Цель:** подключить эталонный набор к codegen и зафиксировать `conformanceSuiteVersion` по [RFC-conformance-0.1.md](../../../RFC-conformance-0.1.md) §7.
+
+**Результат:** [lang/test/conformance/conformance-l5-codegen.test.js](../../test/conformance/conformance-l5-codegen.test.js) — загрузка [conformance/suite.json](../../../conformance/suite.json), фильтр `expect === 'accept'` и **`requireJs === true`** (см. также `filterCasesForL5CodegenRunner` в [conformance-runner.js](../../test/conformance/conformance-runner.js)). Для каждого кейса: **`sourceRoot` = корень каталога `conformance/`** на диске, **`readFile`** через `buildConformanceReadFile`, **`outDir`** — временная директория (`os.tmpdir` + `mkdtemp`), в **`finally`** — `rmSync(..., { recursive: true })` (политика этапа 9: при падении после части шагов tmp всё равно убирать). Вызов `compileSailToOutDir({ entryPath, outDir, sourceRoot, readFile })`; проверки: `ok`, непустой `emitted`, файлы на диске и непустые, подстрока `export function`, отсутствие динамического `import()`; для `accept-l5-cross-module-codegen` — статический `import`/`from` в сгенерированном entry. Перед codegen повторный проход L3 тем же `readFile`; при **`requireIr`** — `buildSerializedIrDocumentFromEnv` и [assertSerializedIrDocumentOk](../../test/ir/ir-document-assert.js), поле **`expectIrSchema`** сверяется с корнем документа.
+
+**Как обновлять ожидания при изменении набора:** поднять **`conformanceSuiteVersion`** в `conformance/suite.json` (RFC-conformance §7) и ту же строку в **`EXPECTED_CONFORMANCE_SUITE_VERSION`** в `conformance-runner.js`; при новых полях кейса — расширить фильтр/ассерты в этом тесте осознанно. Золотой текст JS в манифесте в объёме этапа 10 не используется.
+
+**Критерий приёмки:** `npm test` в `lang/` зелёный; все accept-кейсы с `requireJs: true` проходят раннер; версия в JSON и константе раннера совпадают.
+
+---
+
+## Зависимости между этапами (сводка)
+
+```mermaid
+flowchart LR
+  E0[0 Драйвер] --> E1[1 Тело irSteps]
+  E1 --> E2[2 Quotation call/HO]
+  E2 --> E3[3 Один ESM]
+  E3 --> E4[4 Граф out-dir]
+  E4 --> E5[5 Async]
+  E1 --> E6[6 ADT]
+  E6 --> E7[7 Builtins полные]
+  E3 --> E7
+  E5 --> E8[8 JSDoc sail]
+  E4 --> E8
+  E7 --> E9[9 Диагностики]
+  E8 --> E9
+  E9 --> E10[10 Conformance L5]
+```
+
+Этапы 5 и 6 можно развивать параллельно после стабилизации этапа 3; этап 7 логично вести итеративно с этапом 1, но **закрывать** только после прохождения сценариев этапа 6.
+
+---
+
+## Чеклист готовности L5 (для заявления соответствия)
+
+- [ ] Профиль RFC-compile §1.1 соблюдён на всём эталонном наборе L5 (в т.ч. quotation: §6.3 — инлайн при `call`, функция в точке передачи при HO). *(Текущие кейсы L5 в suite с `requireJs`: одномодульная композиция и кросс-модульный импорт — раннер этапа 10 не доказывает весь §1.1.)*
+- [x] Статические `import` для sail-графа на кросс-модульном conformance-кейсе; в эмитах раннера L5 нет динамического `import()`; спецификаторы с эталоном §9.2 не сравниваются.
+- [ ] FFI-граница §6.1 / RFC-0.1 §10.1 на экспортируемых словах *(нет эталонного FFI-кейса L5 в suite).*
+- [ ] `+Async` / `await` по §10 там, где IR маркирует async.
+- [x] `@sail` на сгенерированных экспортах §11 *(покрыто тестами этапа 8; раннер этапа 10 отдельно не проверяет).*
+- [ ] Выход синтаксически валиден как ESM **ES2025** (RFC-compile §13).
+- [ ] Драйвер не эмитит JS при не-`ok` L3/IR для целевого набора модулей; при не-`ok` codegen после успешного L3 возвращаются диагностики **E51xx**–**E53xx** без гарантии чистого `out-dir` *(поведение драйвера и коды ошибок покрыты `compile-stage0.test.js` и `emit-diagnostics-stage9.test.js`; эталонный L5 conformance негативы codegen не гоняет — для строки чеклиста как «полного» L5-пакета пункт остаётся открытым).*
+
+После выполнения — обновить при необходимости описание уровня L5 в документации пакета `lang` (вне этого файла — по отдельному запросу).

package/lib/codegen/codegen-diagnostics.js

@@ -0,0 +1,164 @@
+/**
+ * Диагностики чистого codegen (RFC-compile-0.1 §12): коды E51xx–E53xx, сообщения, поле `path` где уместно.
+ * Коды E1xxx–E14xx в RFC-0.1 §13 относятся к parse/names/typecheck/runtime; блок E5xxx — контракт репозитория для L5.
+ */
+import path from 'node:path'
+
+/**
+ * @param {{ code: string, message: string, path?: string }} d
+ * @returns {{ code: string, message: string, path?: string }}
+ */
+export function codegenDiagnostic (d) {
+  const out = { code: d.code, message: d.message }
+  if (d.path != null) out.path = path.normalize(path.resolve(d.path))
+  return out
+}
+
+/** @param {string} sailPath */
+export function e5101SailOutsideSourceRoot (sailPath) {
+  return codegenDiagnostic({
+    code: 'E5101',
+    message:
+      'Sail module path is outside source-root (RFC-compile §9.2)',
+    path: sailPath
+  })
+}
+
+/** @param {string} sailPath */
+export function e5101SailInvalidRelative (sailPath) {
+  return codegenDiagnostic({
+    code: 'E5101',
+    message: 'Invalid relative path from source-root to module',
+    path: sailPath
+  })
+}
+
+/** @param {string} sailPath */
+export function e5102SailExpectedExtension (sailPath) {
+  return codegenDiagnostic({
+    code: 'E5102',
+    message: 'Expected .sail module path for codegen output mapping',
+    path: sailPath
+  })
+}
+
+/** @param {string} jsPath */
+export function e5103FfiOutsideSourceRoot (jsPath) {
+  return codegenDiagnostic({
+    code: 'E5103',
+    message: 'FFI .js path is outside source-root (RFC-compile §9.2)',
+    path: jsPath
+  })
+}
+
+/** @param {string} jsPath */
+export function e5103FfiInvalidRelative (jsPath) {
+  return codegenDiagnostic({
+    code: 'E5103',
+    message: 'Invalid relative path from source-root to FFI .js',
+    path: jsPath
+  })
+}
+
+/** @param {string} jsPath */
+export function e5104FfiExpectedExtension (jsPath) {
+  return codegenDiagnostic({
+    code: 'E5104',
+    message: 'Expected .js path for project FFI output mapping',
+    path: jsPath
+  })
+}
+
+/**
+ * Точка входа компиляции не лежит в дереве source-root (явный sourceRoot).
+ *
+ * @param {{ entryPath: string, sourceRoot: string }} opts
+ */
+export function e5105EntryOutsideSourceRoot ({ entryPath, sourceRoot }) {
+  return codegenDiagnostic({
+    code: 'E5105',
+    message: `entryPath is outside source-root (RFC-compile §9.2): ${JSON.stringify(path.normalize(path.resolve(entryPath)))} not under ${JSON.stringify(path.normalize(path.resolve(sourceRoot)))}`,
+    path: entryPath
+  })
+}
+
+/** @param {string} alias */
+export function e5201BadImportAlias (alias) {
+  return codegenDiagnostic({
+    code: 'E5201',
+    message: `Недопустимый идентификатор алиаса модуля для import: ${JSON.stringify(alias)}`
+  })
+}
+
+/** @param {string} alias */
+export function e5202ImportEmptySpecifier (alias) {
+  return codegenDiagnostic({
+    code: 'E5202',
+    message: `Импорт ${alias}: нет resolvedPath к .sail и пустой path (npm ожидает непустой спецификатор)`
+  })
+}
+
+/** @param {string} w */
+export function e5203BadBracketWord (w) {
+  return codegenDiagnostic({
+    code: 'E5203',
+    message: `Недопустимое имя слова в скобках импорта: ${JSON.stringify(w)}`
+  })
+}
+
+/** @param {string} wname */
+export function e5204BadJsWordName (wname) {
+  return codegenDiagnostic({
+    code: 'E5204',
+    message: `Недопустимое имя слова для JS: ${JSON.stringify(wname)}`
+  })
+}
+
+/** @param {string} detail */
+export function e5205EmitAdtAutogen (detail) {
+  return codegenDiagnostic({
+    code: 'E5205',
+    message: `emit ADT autogen: ${detail}`
+  })
+}
+
+/** @param {string} wname */
+export function e5205EmitWord (wname, detail) {
+  return codegenDiagnostic({
+    code: 'E5205',
+    message: `emit ${wname}: ${detail}`
+  })
+}
+
+/** @param {string} detail */
+export function e5206JSDocModuleHeader (detail) {
+  return codegenDiagnostic({
+    code: 'E5206',
+    message: `JSDoc @sail (заголовок модуля): ${detail}`
+  })
+}
+
+/** @param {string} wname */
+export function e5206JSDocWord (wname, detail) {
+  return codegenDiagnostic({
+    code: 'E5206',
+    message: `JSDoc @sail (${wname}): ${detail}`
+  })
+}
+
+export function e5301ReadFileRequired () {
+  return codegenDiagnostic({
+    code: 'E5301',
+    message:
+      'readFile is required for codegen emit when project FFI .js modules are in the closure (RFC-compile §9.1)'
+  })
+}
+
+/** @param {string} jsPath */
+export function e5302CannotReadFfi (jsPath) {
+  return codegenDiagnostic({
+    code: 'E5302',
+    message: `Cannot read FFI file for copy: ${jsPath}`,
+    path: jsPath
+  })
+}