flang: связывание модулей — «использует» начинает действовать

Конструкция `использует «Модуль» из "путь"` разбиралась, но не работала:
парсер складывал импорт в legacy, а имена из другого файла оставались
несвязанными и падали с FLANG_UNKNOWN_NAME на первом же вызове. Из-за этого
stdlib нельзя было применить в решении, а ядро FTS, разложенное по слоям
(лексер, парсер, вычислитель, печать JSON), не собиралось в одну программу —
то есть переписывание ядра на flang было заблокировано.

Импорт сделан слиянием объявлений, а не пространством имён. Пространства имён
потребовали бы решить, как выглядит квалифицированное имя по-русски, и тащить
это решение во все восемь бэкендов; слияние печатается в любой целевой язык
одинаково. Цена — конфликт имён стал ошибкой FLANG_DUPLICATE_NAME с указанием
обоих файлов, а не молчаливым перекрытием.

Связывание двухпроходное, и это не оптимизация, а необходимость: имя функции
без аргументов становится вызовом только если такая функция объявлена, а на
первом проходе каждый файл знает лишь свои объявления. Поэтому parse() принял
третий аргумент — имена, пришедшие из импортов, — и файлы с импортами
разбираются заново уже с полным набором. Без этого транзитивный импорт
(В → Б → А) оставлял вызов несвязанным.

Отказы громкие: пропавший файл — FLANG_IMPORT_NOT_FOUND, цикл —
FLANG_IMPORT_CYCLE с цепочкой, несовпадение имени модуля с заголовком файла —
FLANG_IMPORT_NAME. `экспортирует` ограничивает видимое; у входного файла видно
всё. Файл без импортов разбирается ровно как прежде — это проверяется
побайтовым сравнением AST.

Попутно найдено и записано в SPEC ограничение, не связанное со связыванием:
вариант, названный ключевым словом (`Да`, `Плюс`, `Больше`), в образце не
разбирается, потому что лексер решает раньше, чем известен тип. Диагностика
при этом не называет причину — записано долгом.

Проверено: 723 теста flang, 0 падений (было 712).

Author: the-homeless-god

flang/SPEC.md

@@ -286,3 +286,24 @@ const verdict = checkFacts(program, { facts: {...}, claims: ["…"] })
 свойства как постусловия, примеры как `examples`). Тест обязан прогнать **все**
 модели репозитория через оба движка и потребовать совпадения результатов,
 включая коды ошибок при нарушении свойств.
+
+## 10. Известные ограничения
+
+### Имя варианта не должно совпадать с ключевым словом
+
+Лексер решает, что перед ним, до того как становится известен тип, поэтому
+вариант, названный ключевым словом языка, в образце не разбирается:
+
+| Имя варианта | Во что превращается | Что видно пользователю |
+|---|---|---|
+| `Да`, `Нет` | литерал признака | `FLANG_TYPE`: образец-литерал вместо варианта |
+| `Плюс`, `Минус` | арифметический оператор | `FLANG_PARSE`: ожидался образец |
+| `Больше`, `Меньше` | сравнение | `FLANG_PARSE`: ожидался образец |
+
+Обходится переименованием варианта либо явной формой `случай вариант «Имя»`,
+которой пользуется stdlib. Диагностика при этом не называет настоящую причину —
+это долг: сообщение обязано говорить «имя варианта совпадает с ключевым словом»,
+а не «ожидался образец».
+
+Ограничение обнаружено при связывании модулей и не связано с ним: тот же код в
+одном файле ведёт себя так же.

flang/bin/flang.mjs

@@ -192,6 +192,27 @@ async function parseFlang(source, file) {
     )
   }
   if (typeof parse !== "function") throw fail("FLANG_PARSE", "в parser.mjs нет функции разбора")
+
+  /* Со стандартного ввода нет каталога, относительно которого разрешается
+     `использует … из "…"`, поэтому связывание для него не запускаем: честный
+     FLANG_UNKNOWN_NAME лучше, чем чтение файла из случайного каталога. */
+  if (file !== "-") {
+    const { linkProgram, importsOf } = await import(new URL("../src/link.mjs", import.meta.url).href)
+    /* Разбираем сначала сами: у файла без импортов результат обязан остаться
+       побайтово прежним, иначе `ast` начнёт отличаться там, где ничего не
+       менялось. */
+    const single = parse(source, file)
+    if (importsOf(single).length === 0) return single
+    const linked = await linkProgram(file, source, parse)
+    if (linked.diagnostics.length > 0) {
+      const error = new Error(linked.diagnostics[0].message)
+      error.diagnostics = linked.diagnostics
+      throw error
+    }
+    const { diagnostics: _ignored, ...program } = linked
+    return program
+  }
+
   /* Ошибку самого разбора не заворачиваем: у неё уже есть код, сообщение и
      span — подменять их своим текстом значит потерять место ошибки. */
   return parse(source, file)

flang/core/SPEC.md

@@ -0,0 +1,138 @@
+# Ядро FTS на flang — контракт
+
+Цель: переписать ядро FTS (сейчас `src/*.ts`, 3155 строк) на flang, чтобы
+печатать его в C и получить нативный `fts` без Node — и дальше в остальные
+целевые языки.
+
+## Почему это стало возможно только сейчас
+
+В `tools/ftsc/self/meta.fts` записано ограничение, из-за которого ядро нельзя
+было написать на самом FTS:
+
+> в ядре FTS строка является типом поля, но не значением, над которым можно
+> вычислять
+
+Парсер — это вычисления над строками. flang снимает ровно это ограничение:
+строки в нём данные, а `flang/stdlib/strings.flang` уже даёт `Разбить по
+символу`, `Позиция подстроки`, `Начинается с`, `Считать символ`.
+
+## Разбиение и границы
+
+Слои пишутся независимо и стыкуются только через типы этого файла. Никакой
+слой не разбирает текст повторно и не заглядывает внутрь чужого слоя.
+
+```
+текст .fts ──[лексер]──> список «Токен» ──[парсер]──> «Документ»
+                                                          │
+                                        ┌─────────────────┴───────────────┐
+                                   [вычислитель]                     [печать JSON]
+                              значение / диагностика            строка, байт в байт
+                                                                  как у ядра на TS
+```
+
+## 1. Токены — контракт лексера
+
+```flang
+тип «Токен»
+  вариант ОтступБольше
+  вариант ОтступМеньше
+  вариант КонецСтроки
+  вариант Имя содержит текст: строка
+  вариант Число содержит значение: число
+  вариант Конец
+```
+
+Правила:
+
+- `«имя в кавычках»` и `имя без кавычек` дают один и тот же вариант `Имя`;
+  кавычки-ёлочки снимаются, внутренние пробелы сохраняются. Различать их
+  дальше не нужно: ядро на TS этого различия тоже не хранит.
+- Комментарий `//` до конца строки выбрасывается лексером.
+- Пустая строка не порождает `КонецСтроки`.
+- Отступ — только пробелы, шаг фиксируется первым отступом файла; рваный
+  отступ — диагностика `FTS_INDENT`.
+- Число — целое или с точкой, минус допустим. Разбор обязан совпадать с
+  `Number(...)` ядра.
+
+## 2. Документ — контракт парсера
+
+Дословно повторяет `FtsDocument` из `src/model.ts`. Суммы типов вместо
+размеченных объединений TypeScript:
+
+```flang
+тип «Операнд»
+  вариант Значение содержит значение: строка      // скаляр в текстовом виде
+  вариант Поле содержит имя: строка
+  вариант Процент содержит процент: число, поле: строка
+  вариант Результат
+
+тип «Сравнение»
+  вариант Равно
+  вариант НеРавно
+  вариант НеМеньше
+  вариант НеБольше
+  вариант Больше
+  вариант Меньше
+
+объект «Условие»
+  поле: строка
+  сравнение: «Сравнение»
+  операнд: «Операнд»
+
+объект «Правило»
+  имя: строка
+  условия: список «Условие»
+  действие: «Действие»          // Присвоить | Добавить, оба с операндом
+
+объект «Свойство»
+  имя: строка
+  сравнение: «Сравнение»
+  операнд: «Операнд»
+
+объект «Пример»
+  имя: строка
+  вход: список «Привязка»       // имя поля → скаляр
+  ожидается: строка
+
+объект «Утилита»
+  имя: строка
+  принимает: строка
+  возвращает: строка
+  начальное: строка
+  правила: список «Правило»
+  свойства: список «Свойство»
+  примеры: список «Пример»
+```
+
+Соответствие поверхности: `не меньше` → `НеМеньше`, `равен` → `Равно`,
+`да`/`нет` → скаляр признака, `N процентов от поля X` → `Процент`.
+
+## 3. Семантика вычислителя
+
+Обязана совпадать с `src/utility.ts` и с таблицей в `flang/SPEC.md`:
+
+| Вопрос | Решение |
+|---|---|
+| проценты | `(процент / 100) * значение` — именно в этом порядке |
+| равенство скаляров | `Object.is` |
+| порядок правил | сверху вниз, `Добавить` накапливает, `Присвоить` затирает |
+| свойство | постусловие на **всей** области входа, проверяется после всех правил |
+| нарушено свойство | код `FTS_UTILITY_PROPERTY`, текст ровно как у ядра |
+| пример не сошёлся | код `FTS_EXAMPLE_MISMATCH` |
+
+Свойство проверяется и тогда, когда ни одно правило не сработало — именно
+из-за этого процентный предел на отрицательной сумме падал.
+
+## 4. Тотальность
+
+Всё ядро обязано лежать в тотальном классе: `fts check` не имеет права
+зависнуть. Циклы «пока есть символы» выражаются свёрткой по списку символов —
+он структурно убывает. Где тотальность не доказывается, признак `тотальная`
+не ставится, а место записывается в этот файл как долг с объяснением.
+
+## 5. Критерий готовности — дифференциальная сверка
+
+Ядро считается верным не тогда, когда проходят его собственные тесты, а когда
+на **всех** `.fts` репозитория старое ядро на TS и новое на flang дают
+побайтово совпадающий JSON — включая коды и тексты диагностик. Приём уже
+отработан в `flang/src/compat.mjs`: 19 593 входа, ноль расхождений.

flang/examples/import-check.flang

@@ -0,0 +1,10 @@
+модуль «Проба импорта»
+  использует «Списки» из "../stdlib/lists.flang"
+
+тотальная функция «Сумма пробы»
+  принимает элементы: список числа
+  возвращает число
+  «Сумма» от элементы
+  пример «Четыре числа»
+    дано элементы равно [1, 2, 3, 40]
+    ожидается результат равен 46