@boristype/bt-ir 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BorisType
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+# bt-ir
+
+**IR-based компилятор TypeScript → BorisScript**
+
+bt-ir — бэкенд компиляции для [BorisType](../README.md), транспилирующий TypeScript в BorisScript через промежуточное представление (IR).
+
+## Обзор
+
+- **Вход:** TypeScript исходный код
+- **Выход:** BorisScript (.js файлы)
+- **Метод:** TypeScript AST → IR (Intermediate Representation) → BorisScript
+
+**Зачем IR?** Проще, легче поддерживать и корректнее, чем предыдущий подход на основе трансформеров.
+
+## Установка
+
+```bash
+npm install bt-ir
+```
+
+## API
+
+### compile(sourceCode, options?)
+
+Компилирует строку TypeScript исходного кода.
+
+```typescript
+import { compile } from "bt-ir";
+
+const result = compile(`
+  const greet = (name: string) => {
+    alert(\`Hello, \${name}!\`);
+  };
+  greet("World");
+`, {
+  filename: "test.ts",
+  compileMode: "script"
+});
+
+console.log(result.outputs[0].code);
+```
+
+**Параметры:**
+- `sourceCode: string` — TypeScript код для компиляции
+- `options?: CompileOptions` — Опции компиляции
+
+**Возвращает:** `CompileResult`
+
+### compileFile(filePath, options?)
+
+Компилирует TypeScript файл.
+
+```typescript
+import { compileFile } from "bt-ir";
+
+const result = compileFile("./src/index.ts", {
+  compileMode: "module"
+});
+
+console.log(result.outputs[0].code);
+```
+
+**Параметры:**
+- `filePath: string` — Путь к TypeScript файлу
+- `options?: CompileOptions` — Опции компиляции
+
+**Возвращает:** `CompileResult`
+
+### compileSourceFile(sourceFile, program, options?)
+
+Компилирует TypeScript SourceFile (для интеграции с существующим TypeScript Program).
+
+```typescript
+import ts from "typescript";
+import { compileSourceFile } from "bt-ir";
+
+const program = ts.createProgram(["src/index.ts"], {});
+const sourceFile = program.getSourceFile("src/index.ts")!;
+
+const result = compileSourceFile(sourceFile, program, {
+  compileMode: "module",
+  cwd: process.cwd()
+});
+
+console.log(result.outputs[0].code);
+```
+
+**Параметры:**
+- `sourceFile: ts.SourceFile` — TypeScript SourceFile для компиляции
+- `program: ts.Program` — Экземпляр TypeScript Program  
+- `options?: CompileOptions` — Опции компиляции
+
+**Возвращает:** `CompileResult`
+
+## Типы
+
+### CompileOptions
+
+```typescript
+interface CompileOptions {
+  /** Режим компиляции: bare, script или module */
+  compileMode?: "bare" | "script" | "module";
+  
+  /** Текущая рабочая директория (для разрешения относительных путей) */
+  cwd?: string;
+  
+  /** Имя исходного файла (для функции compile()) */
+  filename?: string;
+}
+```
+
+### CompileResult
+
+```typescript
+interface CompileResult {
+  /** Результаты компиляции (обычно один файл) */
+  outputs: CompileOutput[];
+  
+  /** Диагностика TypeScript (ошибки/предупреждения) */
+  diagnostics: ts.Diagnostic[];
+  
+  /** Флаг успеха */
+  success: boolean;
+}
+```
+
+### CompileOutput
+
+```typescript
+interface CompileOutput {
+  /** Путь к выходному файлу (относительно входного) */
+  path: string;
+  
+  /** Сгенерированный BorisScript код */
+  code: string;
+  
+  /** Source map (если включено) */
+  map?: string;
+}
+```
+
+## Режимы компиляции
+
+bt-ir поддерживает три режима компиляции:
+
+| Режим | Назначение | Возможности |
+|------|----------|-------|
+| **bare** | Runtime polyfills, встроенные модули | Минимальный вывод, нет bt.* обёрток |
+| **script** | Тестовые файлы, executable объекты | Полные возможности с bt.getProperty, polyfills |
+| **module** | Codelibrary пакеты (по умолчанию) | Обёрнуто в __init(), hoisting переменных |
+
+См. [Справка по режимам компиляции](../docs/reference/compile-modes.md) для деталей.
+
+## Примеры
+
+### Базовое использование
+
+```typescript
+import { compile } from "bt-ir";
+
+const result = compile(`
+  function add(a: number, b: number): number {
+    return a + b;
+  }
+  
+  const result = add(2, 3);
+  alert(result);
+`);
+
+if (result.success) {
+  console.log(result.outputs[0].code);
+}
+```
+
+### С конкретным режимом
+
+```typescript
+import { compile } from "bt-ir";
+
+// Bare mode - минимальный overhead
+const bareResult = compile(`
+  export function fastHash(str: string): number {
+    return str.length;
+  }
+`, { compileMode: "bare" });
+
+// Script mode - полные возможности
+const scriptResult = compile(`
+  const obj = { foo: "bar" };
+  alert(obj.foo);
+`, { compileMode: "script" });
+
+// Module mode - codelibrary
+const moduleResult = compile(`
+  export function greet(name: string) {
+    alert("Hello " + name);
+  }
+`, { compileMode: "module" });
+```
+
+### Интеграция с TypeScript Watch
+
+```typescript
+import ts from "typescript";
+import { compileSourceFile } from "bt-ir";
+
+const host = ts.createWatchCompilerHost(
+  "tsconfig.json",
+  { noEmit: true }, // TypeScript только для диагностики
+  ts.sys,
+  ts.createProgram,
+  (diagnostic) => console.log(diagnostic.messageText)
+);
+
+const originalAfterProgramCreate = host.afterProgramCreate;
+host.afterProgramCreate = (program) => {
+  originalAfterProgramCreate?.(program);
+  
+  // Emit через bt-ir
+  for (const sourceFile of program.getSourceFiles()) {
+    if (!sourceFile.isDeclarationFile) {
+      const result = compileSourceFile(sourceFile, program);
+      // Записать result.outputs[0].code на диск
+    }
+  }
+};
+
+ts.createWatchProgram(host);
+```
+
+## Архитектура
+
+```
+TypeScript Source
+      ↓
+[TypeScript Parser]  ← TypeScript Compiler API
+      ↓
+[Scope Analyzer]     ← Анализ captured переменных
+      ↓
+[IR Lowering]        ← Преобразование TS AST → IR
+      ↓
+[BT Emitter]         ← Генерация BorisScript
+      ↓
+BorisScript Output
+```
+
+Для детальной архитектуры, см.:
+- [Архитектура IR Pipeline](../ref/architecture/ir-pipeline.md)
+- [Ограничения BorisScript](../docs/reference/borisscript-constraints.md)
+
+## Ключевые возможности
+
+### Автоматические трансформации
+
+- **Стрелочные функции** → Обычные функции с env/desc
+- **Шаблонные литералы** → Конкатенация строк
+- **for...of** → for...in (массивы BorisScript)
+- **let/const** → var с hoisting
+- **Замыкания** → цепочка __env для captured переменных
+- **Доступ к свойствам** → bt.getProperty() (script/module mode)
+- **Вызовы методов** → bt.callFunction() (script/module mode)
+
+### Polyfills
+
+Автоматическое внедрение polyfill для:
+- Методы массивов: map, filter, reduce, forEach, ...
+- Методы строк: split, trim, substring, ...
+- Методы чисел: toFixed, toString, ...
+
+### Анализ Scope
+
+- Обнаруживает captured переменные в замыканиях
+- Генерирует минимальную цепочку __env
+- Правильный variable hoisting
+
+## CLI (Разработка)
+
+bt-ir включает CLI для тестирования:
+
+```bash
+# Компилировать один файл
+node --experimental-strip-types src/cli.ts example/src/index.ts
+
+# Компилировать с выводом
+node --experimental-strip-types src/cli.ts example/src/index.ts -o example/build/index.js
+
+# После сборки
+npm run build
+node build/cli.js example/src/index.ts
+```
+
+## Разработка
+
+```bash
+# Установить зависимости
+npm install
+
+# Собрать
+npm run build
+
+# Запустить тесты
+npm test
+
+# Разработка с примерами
+npm run build && node build/cli.js example/src/index.ts
+```
+
+## Структура проекта
+
+```
+bt-ir/
+├── src/
+│   ├── index.ts          # Public API
+│   ├── pipeline/         # Конвейер компиляции
+│   ├── analyzer/         # Анализ scope
+│   ├── ir/               # Определения IR нод
+│   ├── lowering/         # Трансформация TS AST → IR
+│   └── emitter/          # Генерация IR → BorisScript
+├── example/              # Примеры использования
+├── build/                # Скомпилированный вывод
+└── README.md             # Этот файл
+```
+
+## Версия TypeScript
+
+Требуется TypeScript 5.0+
+
+## Лицензия
+
+MIT
+
+## См. также
+
+- [Основной проект BorisType](../)
+- [Компилятор btc](../btc/)
+- [Справка по режимам компиляции](../docs/reference/compile-modes.md)
+- [Ограничения BorisScript](../docs/reference/borisscript-constraints.md)
+- [Архитектура IR Pipeline](../ref/architecture/ir-pipeline.md)

package/build/analyzer/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Analyzer module - анализ исходного кода
+ *
+ * @module analyzer
+ */
+export { analyzeScopes, printScopeTree, getEnvDepth, getCodelibraryDepth, type Scope, type VariableInfo, type ScopeAnalysisResult, } from "./scope-analyzer.ts";
+//# sourceMappingURL=index.d.ts.map

package/build/analyzer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analyzer/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,aAAa,EACb,cAAc,EACd,WAAW,EACX,mBAAmB,EACnB,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC"}

package/build/analyzer/index.js

@@ -0,0 +1,7 @@
+/**
+ * Analyzer module - анализ исходного кода
+ *
+ * @module analyzer
+ */
+export { analyzeScopes, printScopeTree, getEnvDepth, getCodelibraryDepth, } from "./scope-analyzer.js";
+//# sourceMappingURL=index.js.map

package/build/analyzer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analyzer/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,aAAa,EACb,cAAc,EACd,WAAW,EACX,mBAAmB,GAIpB,MAAM,qBAAqB,CAAC"}

package/build/analyzer/scope-analyzer.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Scope Analyzer - анализ областей видимости и захваченных переменных
+ *
+ * Определяет какие переменные используются во вложенных scopes (captured)
+ * и строит дерево scopes для генерации __env chain.
+ *
+ * @module analyzer
+ */
+import * as ts from "typescript";
+import { BindingManager } from "../lowering/binding.ts";
+/**
+ * Информация о переменной
+ */
+export interface VariableInfo {
+    /** Имя переменной */
+    name: string;
+    /** Тип объявления */
+    kind: "const" | "let" | "var" | "function" | "parameter" | "import";
+    /** Scope где объявлена переменная */
+    declarationScope: Scope;
+    /** Используется ли во вложенных scopes (требует __env) */
+    isCaptured: boolean;
+    /** Scopes где используется эта переменная */
+    usedInScopes: Set<Scope>;
+    /** Переименованное имя (если shadowing) */
+    renamedTo?: string;
+}
+/**
+ * Область видимости
+ */
+export interface Scope {
+    /** Уникальный id scope */
+    id: number;
+    /** Тип scope */
+    type: "module" | "function" | "block";
+    /** Имя (для функций) */
+    name?: string;
+    /** Родительский scope */
+    parent: Scope | null;
+    /** Дочерние scopes */
+    children: Scope[];
+    /** Переменные объявленные в этом scope */
+    variables: Map<string, VariableInfo>;
+    /** Соответствующая TS нода */
+    node: ts.Node;
+    /** Глубина вложенности функций (для генерации __env.__parent chain) */
+    depth: number;
+    /** Есть ли captured переменные в этом scope */
+    hasCaptured: boolean;
+}
+/**
+ * Результат анализа
+ */
+export interface ScopeAnalysisResult {
+    /** Корневой scope (module) */
+    moduleScope: Scope;
+    /** Все scopes по id */
+    scopesById: Map<number, Scope>;
+    /** Карта: TS Node -> Scope */
+    nodeToScope: Map<ts.Node, Scope>;
+    /** Все captured переменные */
+    capturedVariables: VariableInfo[];
+    /** Менеджер генерации имён (shared с visitor) */
+    bindings: BindingManager;
+}
+/**
+ * Анализирует scopes в исходном файле
+ * @param sourceFile - TypeScript source file
+ * @param bindings - Менеджер генерации имён (опциональный, создаётся если не передан)
+ */
+export declare function analyzeScopes(sourceFile: ts.SourceFile, bindings?: BindingManager): ScopeAnalysisResult;
+/**
+ * Выводит дерево scopes в консоль (для отладки)
+ */
+export declare function printScopeTree(scope: Scope, indent?: number): void;
+/**
+ * Вычисляет глубину __env chain между двумя scopes
+ * Используется для генерации __env.__parent.__parent...
+ *
+ * Считает только scopes с hasCaptured (которые создают свой __env)
+ */
+export declare function getEnvDepth(fromScope: Scope, toScope: Scope): number;
+/**
+ * Глубина до root __env для lib (__codelibrary).
+ * Считает только block scopes — в module mode function env не создаётся.
+ */
+export declare function getCodelibraryDepth(fromScope: Scope, toScope: Scope): number;
+//# sourceMappingURL=scope-analyzer.d.ts.map

package/build/analyzer/scope-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-analyzer.d.ts","sourceRoot":"","sources":["../../src/analyzer/scope-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,IAAI,EAAE,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;IACpE,qCAAqC;IACrC,gBAAgB,EAAE,KAAK,CAAC;IACxB,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;IACpB,6CAA6C;IAC7C,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACzB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB;IAChB,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;IACtC,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,sBAAsB;IACtB,QAAQ,EAAE,KAAK,EAAE,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,8BAA8B;IAC9B,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;IACd,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8BAA8B;IAC9B,WAAW,EAAE,KAAK,CAAC;IACnB,uBAAuB;IACvB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/B,8BAA8B;IAC9B,WAAW,EAAE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACjC,8BAA8B;IAC9B,iBAAiB,EAAE,YAAY,EAAE,CAAC;IAClC,iDAAiD;IACjD,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAKD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,QAAQ,GAAE,cAAqC,GAC9C,mBAAmB,CAwDrB;AAwgBD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,SAAI,GAAG,IAAI,CAa7D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,GAAG,MAAM,CAapE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,GAAG,MAAM,CAY5E"}