@algosail/lang 0.2.11 → 0.5.0

package/lib/parse/ast-spec.js

@@ -0,0 +1,212 @@
+/**
+ * Sail AST shape for RFC-0.1 §12.2 (phrase structure). Normative grammar is RFC;
+ * this file is the implementation contract for parse output.
+ *
+ * ## Spans
+ * Every node has `span: SourceSpan`. Positions match lexer (1-based line/column).
+ * `end` is the cursor after the last consumed character (exclusive end offset).
+ *
+ * ## Documentation (`doc`, RFC-0.1 п.4.3, грамматика `doc_block` п.12.2)
+ * Where the grammar requires `doc_block` (zero or more `-- … --` each followed by `ws`),
+ * the AST exposes `doc: string[]`: each entry is the inner `comment_text` of one block,
+ * in source order. Use `[]` when the block is empty.
+ * Applies to: leading doc on an import; after sum/product header and type parameters;
+ * after each sum tag and each product field; after the word signature and before the body.
+ *
+ * ## Other comments (AST v1)
+ * Leading `-- … --` before `+` / `&` / `@` are folded into the next declaration’s `doc`;
+ * they are not separate `items` entries. Comments inside a word or quotation body are not
+ * represented as dedicated `word_step` nodes in AST v1 (RFC-0.1 п.12.3).
+ *
+ * @typedef {{ offset: number, line: number, column: number }} SourcePos
+ * @typedef {{ start: SourcePos, end: SourcePos }} SourceSpan
+ *
+ * @typedef {Object} AstSourceFile
+ * @property {'source_file'} kind
+ * @property {SourceSpan} span
+ * @property {AstTopLevel[]} items
+ *
+ * @typedef {AstImport|AstSumType|AstProductType|AstWord} AstTopLevel
+ *
+ * @typedef {Object} AstImport
+ * @property {'import'} kind
+ * @property {SourceSpan} span
+ * @property {string} module
+ * @property {string} path
+ * @property {{ words: string[], types: string[] } | null} [bracket] bracket import list, or null for simple import
+ * @property {string[]} doc `-- … --` blocks immediately before this import (RFC-0.1 п.4.3)
+ *
+ * @typedef {Object} AstSumType
+ * @property {'sum_type'} kind
+ * @property {SourceSpan} span
+ * @property {string} name
+ * @property {string[]} typeParams
+ * @property {string[]} doc after `&TypeName` and type parameters, before first `|` (RFC-0.1 п.12.2 `sum_type_decl`)
+ * @property {{ name: string, payload: AstTypeExpr | null, span: SourceSpan, doc: string[] }[]} tags
+ *
+ * @typedef {Object} AstProductType
+ * @property {'product_type'} kind
+ * @property {SourceSpan} span
+ * @property {string} name
+ * @property {string[]} typeParams
+ * @property {string[]} doc after header and type parameters, before first field (RFC-0.1 п.12.2 `product_type_decl`)
+ * @property {{ name: string, type: AstTypeExpr, span: SourceSpan, doc: string[] }[]} fields
+ *
+ * @typedef {Object} AstWord
+ * @property {'word'} kind
+ * @property {SourceSpan} span
+ * @property {string} name
+ * @property {AstSignature} signature
+ * @property {string[]} doc after signature, before first `word_step` (RFC-0.1 п.12.2 `word_decl`, п.4.3)
+ * @property {AstWordStep[]} body
+ *
+ * @typedef {Object} AstSignature
+ * @property {'signature'} kind
+ * @property {SourceSpan} span
+ * @property {AstSigStackItem[]} left stack slots only (RFC-0.1 п.12.2 `sig_item` except `effect_add` / `effect_remove`)
+ * @property {AstSigStackItem[]} right
+ * @property {AstSigEffectAdd[]} effectsAdd `+EffectName` (RFC-0.1 п.5.7, `effect_add`); order = source order (`span.start`)
+ * @property {AstSigEffectRemove[]} effectsRemove `-EffectName` (`effect_remove`); same ordering
+ *
+ * @typedef {AstSigStackVar|AstSigQuotation|AstSigNamedQuotation|AstSigTypeExpr} AstSigStackItem
+ * Stack-context variables `~s`, `~b`, … are **AstSigStackVar** (RFC-0.1 п.12.2 `stack_var`), not `AstTypeVar`.
+ *
+ * @typedef {Object} AstSigEffectAdd
+ * @property {'sig_effect_add'} kind
+ * @property {string} name Async | Fail
+ * @property {SourceSpan} span
+ * @property {'left'|'right'} side of `->` this marker belongs to
+ *
+ * @typedef {Object} AstSigEffectRemove
+ * @property {'sig_effect_remove'} kind
+ * @property {string} name Async | Fail
+ * @property {SourceSpan} span
+ * @property {'left'|'right'} side of `->` this marker belongs to
+ *
+ * @typedef {Object} AstSigStackVar
+ * Stack type / stack-context variable: source form `~` + `LowerIdent` (RFC-0.1 п.12.2 `stack_var`, п.12.3 п.10–11).
+ * Examples: `~s`, `~b`, `~rest`. Distinct from `~Module/Type` (**AstModuleTypeRef**) and from type parameters like `a` in `Maybe a` (**AstTypeVar** in **AstTypeExpr**).
+ * @property {'stack_var'} kind
+ * @property {string} name `LowerIdent` only, **without** the leading `~` (e.g. `"s"` for `~s`)
+ * @property {SourceSpan} span
+ *
+ * @typedef {Object} AstSigQuotation
+ * @property {'quotation_sig'} kind
+ * @property {SourceSpan} span
+ * @property {AstSignature} inner same shape as top-level `signature` (left/right stack items + effectsAdd/effectsRemove)
+ *
+ * @typedef {Object} AstSigNamedQuotation
+ * @property {'named_quotation_sig'} kind
+ * @property {string} prefix
+ * @property {AstSigQuotation} quotation
+ * @property {SourceSpan} span
+ *
+ * @typedef {Object} AstSigTypeExpr
+ * @property {'sig_type_expr'} kind
+ * @property {AstTypeExpr} type
+ * @property {SourceSpan} span
+ *
+ * @typedef {Object} AstQuotationType
+ * Типовое выражение `Quote ( In -> Out )` / вложенная сигнатура в аргументе (напр. `Maybe ( Num -> Str )`).
+ * @property {'quotation_type'} kind
+ * @property {AstSignature} inner та же форма, что `quotation_sig.inner`
+ *
+ * @typedef {AstTypeName|AstTypeVar|AstModuleTypeRef|AstParenType|AstTypeApp|AstQuotationType} AstTypeExpr
+ *
+ * @typedef {Object} AstTypeName
+ * @property {'type_name'} kind
+ * @property {string} name
+ *
+ * @typedef {Object} AstTypeVar
+ * Type parameter in `type_expr` / `sig_type_expr` (RFC-0.1 `TypeVar`), not a stack slot `~name` — that is **AstSigStackVar** in **AstSigStackItem**.
+ * @property {'type_var'} kind
+ * @property {string} name
+ *
+ * @typedef {Object} AstModuleTypeRef
+ * @property {'module_type_ref'} kind
+ * @property {string} module
+ * @property {string} type
+ *
+ * @typedef {Object} AstParenType
+ * @property {'paren_type'} kind
+ * @property {AstTypeExpr} inner
+ *
+ * @typedef {Object} AstTypeApp
+ * @property {'type_app'} kind
+ * @property {string} ctor List | Dict | Map or generic head name
+ * @property {AstTypeExpr[]} args
+ *
+ * @typedef {AstLiteral|AstWordRef|AstModuleWordRef|AstBuiltin|AstQuotation|AstListLiteral|AstSlotWrite|AstSlotRead} AstWordStep
+ *
+ * @typedef {Object} AstLiteral
+ * @property {'literal'} kind
+ * @property {SourceSpan} span
+ * @property {'string'|'number'|'bigint'|'regexp'|'nil'|'bool'} litKind
+ * @property {string} raw lexer text
+ *
+ * @typedef {Object} AstWordRef
+ * @property {'word_ref'} kind
+ * @property {SourceSpan} span
+ * @property {string} name
+ *
+ * @typedef {Object} AstModuleWordRef
+ * @property {'module_word_ref'} kind
+ * @property {SourceSpan} span
+ * @property {string} module
+ * @property {string} word
+ *
+ * @typedef {Object} AstBuiltin
+ * @property {'builtin'} kind
+ * @property {SourceSpan} span
+ * @property {string} name
+ *
+ * @typedef {Object} AstQuotation
+ * @property {'quotation'} kind
+ * @property {SourceSpan} span
+ * @property {AstWordStep[]} body
+ *
+ * @typedef {Object} AstListLiteral
+ * @property {'list_literal'} kind
+ * @property {SourceSpan} span
+ * @property {AstLiteral[]} elements
+ *
+ * @typedef {Object} AstSlotWrite
+ * @property {'slot_write'} kind
+ * @property {SourceSpan} span
+ * @property {string} name
+ *
+ * @typedef {Object} AstSlotRead
+ * @property {'slot_read'} kind
+ * @property {SourceSpan} span
+ * @property {string} name
+ */
+
+/** @type {readonly string[]} */
+export const AST_KINDS = Object.freeze([
+  'source_file',
+  'import',
+  'sum_type',
+  'product_type',
+  'word',
+  'signature',
+  'sig_effect_add',
+  'sig_effect_remove',
+  'stack_var',
+  'quotation_sig',
+  'named_quotation_sig',
+  'sig_type_expr',
+  'type_name',
+  'type_var',
+  'module_type_ref',
+  'paren_type',
+  'quotation_type',
+  'type_app',
+  'literal',
+  'word_ref',
+  'module_word_ref',
+  'builtin',
+  'quotation',
+  'list_literal',
+  'slot_write',
+  'slot_read'
+])

package/lib/parse/builtins-set.js

@@ -0,0 +1,12 @@
+/**
+ * Нормативный перечень builtin_word (RFC-builtins-0.1.md резюме §4).
+ */
+export const BUILTIN_WORDS = new Set([
+  'dup', 'drop', 'swap', 'over', 'dup2', 'drop2',
+  'rot', 'reverse', 'nip', 'tuck', 'swap2',
+  'call', 'dip', 'keep', 'bi', 'tri', 'spread', 'both'
+])
+
+export function isBuiltinWord (name) {
+  return BUILTIN_WORDS.has(name)
+}

package/lib/parse/diagnostics.js

@@ -0,0 +1,180 @@
+/** RFC-0.1 §13 templates for parse/lex (E1001–E1007). */
+
+export function e1001UnexpectedToken (token) {
+  return `Синтаксическая ошибка: неожиданный токен '${token}'.`
+}
+
+export function e1002UnclosedComment () {
+  return "Незакрытый комментарий: ожидалась закрывающая пара '--'."
+}
+
+export function e1003BadImportPath (path) {
+  return `Некорректный путь импорта '${path}'.`
+}
+
+export function e1004UnknownBlock (token) {
+  return `Неизвестный блок '${token}'. Ожидался '+', '&' или '@'.`
+}
+
+export function e1005ArrowInQuotation () {
+  return "Стрелка сигнатуры '->' допустима только в сигнатурах, не внутри тела исполняемого '( ... )'."
+}
+
+export function e1006EffectOutsideSignature (effect) {
+  return `Префикс эффекта '${effect}' допустим только внутри сигнатуры в скобках.`
+}
+
+export function e1007EffectOnlyAfterArrow (marker) {
+  return `Маркер эффекта '${marker}' допустим только справа от '->' в сигнатуре (исходящая часть).`
+}
+
+/** RFC-0.1 §13 — E1101–E1113 (декларации, импорты, FFI). */
+
+export function e1101DuplicateWord (name) {
+  return `Слово '${name}' уже объявлено в текущем модуле.`
+}
+
+export function e1102DuplicateType (name) {
+  return `Тип '${name}' уже объявлен в текущем модуле.`
+}
+
+export function e1103DuplicateSumTag (tag) {
+  return `Тег '${tag}' уже использован в sum-типе этого модуля.`
+}
+
+export function e1104DuplicateProductField (field, type) {
+  return `Поле '${field}' уже объявлено в типе '${type}'.`
+}
+
+export function e1105AutogenNameConflict (name) {
+  return `Автогенерируемое имя '${name}' конфликтует с существующим объявлением.`
+}
+
+export function e1106DuplicateJsSailBlock (name) {
+  return `Повторное объявление '@sail' для '${name}' в JS-модуле.`
+}
+
+export function e1108DuplicateBracketImportName (name) {
+  return `Повторное имя '${name}' в списке скобочного импорта.`
+}
+
+export function e1109BracketImportConflicts (name) {
+  return `Имя '${name}' уже объявлено в модуле или внесено другим импортом; конфликт со скобочным импортом.`
+}
+
+export function e1110SymbolMissingInExport (name) {
+  return `Символ '${name}' отсутствует в экспорте модуля (для JS — в извлечённом контракте '@sail').`
+}
+
+export function e1111DuplicateModuleImport (module) {
+  return `Модуль '${module}' уже импортирован в этом файле.`
+}
+
+export function e1112CyclicSailImports (modules) {
+  return `Циклическая зависимость между модулями Sail (в цикле участвуют, например: ${modules}).`
+}
+
+export function e1113InvalidJsSailJSDoc () {
+  return "Блок JSDoc с '@sail': повторный '@sail', либо текст после '@sail' не является валидным фрагментом Sail (§10.1)."
+}
+
+/** RFC-0.1 §13 — E1201–E1206 (резолв имён). */
+
+export function e1201UnresolvedName (name) {
+  return `Не удалось разрешить имя '${name}'.`
+}
+
+export function e1202AmbiguousName (name) {
+  return `Неоднозначная ссылка '${name}' в текущем модуле.`
+}
+
+export function e1203ModuleNotFound (module) {
+  return `Модуль '${module}' не найден.`
+}
+
+export function e1204MissingMember (module, name) {
+  return `В модуле '${module}' отсутствует '${name}'.`
+}
+
+export function e1205ImportNeedsQualification (name, module) {
+  return `Обращение к '${name}' из модуля '${module}' требует '~${module}/${name}' (если символ не внесён скобочным импортом, §4.2).`
+}
+
+export function e1206UnknownBuiltin (name) {
+  return `Неизвестное встроенное слово '${name}'.`
+}
+
+/** RFC-0.1 §13 E1301 */
+export function e1301WordSignature (word) {
+  return `Некорректная сигнатура слова '${word}'.`
+}
+
+/** RFC-0.1 §13 E1304 */
+export function e1304TypeMismatch (expected, actual) {
+  return `Несовместимые типы: expected ${expected}, got ${actual}.`
+}
+
+/** RFC-0.1 §13 E1304 — неразрешённое имя в типовом слоте сигнатуры (этап 3). */
+export function e1304UnknownTypeInSignature (name) {
+  return `Неизвестное имя типа '${name}' в сигнатуре.`
+}
+
+/** RFC-0.1 §13 E1303 */
+export function e1303StackEffect (expected, actual) {
+  return `Несогласованный стековый эффект: expected ${expected}, got ${actual}.`
+}
+
+/** RFC-0.1 §13 E1305 ({var} в RFC) */
+export function e1305OccursCheck (varName) {
+  return `Бесконечный тип недопустим: переменная '${varName}' входит сама в себя.`
+}
+
+/** RFC-0.1 §13 E1306 */
+export function e1306CallNeedsQuote (actual) {
+  return `Нельзя применить CALL: ожидается Quote (I -> O), получено ${actual}.`
+}
+
+/** RFC-0.1 §13 E1307 */
+export function e1307EliminatorBranches () {
+  return 'Ветки eliminator-а несовместимы: выходные сигнатуры quotations (в т.ч. ~b) не унифицируются.'
+}
+
+/** RFC-0.1 §13 E1308 */
+export function e1308EliminatorQuotes (name) {
+  return `Некорректные аргументы eliminator-а '${name}': quotations должны идти в порядке объявления тегов/полей.`
+}
+
+/** RFC-0.1 §13 E1309 (контейнеры List/Dict/Map — выдача из L3 по мере реализации проверки). */
+export function e1309ContainerContract (type, expected, actual) {
+  return `Нарушение ограничений контейнера '${type}': expected ${expected}, got ${actual}.`
+}
+
+/** RFC-0.1 §13 E1311 */
+export function e1311ParameterizedTypeNeedsParens (type) {
+  return `В сигнатуре параметризованный тип '${type}' должен быть записан в скобках как единый слот (§4.4).`
+}
+
+/** RFC-0.1 §13 E1302 */
+export function e1302QuotationSig (detail) {
+  return `Некорректная сигнатура quotation: '${detail}'.`
+}
+
+/** RFC-0.1 §13 E1313 */
+export function e1313DuplicateSlotWrite (name) {
+  return `Повторная запись слота ':${name}' в теле слова (§6.1.6).`
+}
+
+/** RFC-0.1 §13 E1314 */
+export function e1314SlotReadBeforeWrite (name) {
+  return `Чтение слота ';${name}' до соответствующей записи ':${name}' (§6.1.6).`
+}
+
+/** RFC-0.1 §13 E1310 */
+export function e1310AsyncCall (callee, caller) {
+  return `Вызов '${callee}' с эффектом '+Async' недопустим из слова '${caller}' без '+Async' или без снятия '-Async' обёрткой (§5.7).`
+}
+
+/** RFC-0.1 §13 E1312 */
+export function e1312FailCall (callee, caller) {
+  return `Вызов '${callee}' с эффектом '+Fail' недопустим из '${caller}' без '+Fail' или без снятия '-Fail' обёрткой (§5.7).`
+}

package/lib/parse/index.js

@@ -0,0 +1,46 @@
+/**
+ * Parse phase (RFC-0.1 §11 step 1): lex (RFC-lex-0.1) + phrase parse (§12.2).
+ */
+
+import { createLexerState, skipWs } from './lexer.js'
+import { parseSourceText } from './parse-source.js'
+import * as ab from './ast-build.js'
+
+/**
+ * @param {string} sourceText
+ * @returns {{ ok: boolean, diagnostics: Array<{ code: string, message: string, offset?: number, line?: number, column?: number }>, ast?: unknown }}
+ */
+export function parseSource (sourceText) {
+  if (typeof sourceText !== 'string') {
+    return {
+      ok: false,
+      diagnostics: [{
+        code: 'E1001',
+        message: "Синтаксическая ошибка: неожиданный токен ''.",
+        offset: 0,
+        line: 1,
+        column: 1
+      }]
+    }
+  }
+  if (/^\s*$/.test(sourceText)) {
+    const state = createLexerState(sourceText)
+    skipWs(state)
+    const end = ab.endPosFromState(state)
+    const span = {
+      start: { offset: 0, line: 1, column: 1 },
+      end
+    }
+    return {
+      ok: true,
+      diagnostics: [],
+      ast: ab.node('source_file', span, { items: [] })
+    }
+  }
+  const { diagnostics, ast } = parseSourceText(sourceText)
+  return {
+    ok: diagnostics.length === 0,
+    diagnostics,
+    ast: diagnostics.length === 0 ? ast : undefined
+  }
+}