| 1 | # ECMAScript: редакции, модули и граница совместимости |
| 2 | |
| 3 | **Назначение:** опорный слой **спецификации ECMA-262** и **системы модулей** в реальных проектах: годовые редакции, политика «что допустимо в исходниках без транспиляции», ESM vs CommonJS. Мир **`software.javascript`**. |
| 4 | |
| 5 | **Порядок загрузки:** `status-javascript-v1.md` → `playbook-javascript-operational-v1.md` → этот файл (или по карте `index-knowledge-javascript-cluster-v1.md`). |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## Provenance |
| 10 | |
| 11 | - source_refs: `spec:ECMA-262` (ежегодные редакции; текст на ecma-international.org); `doc:MDN` (обзорные страницы по модулям и `import`); `kb:internal` synthesis 2026-05-10 |
| 12 | - created_at: 2026-05-10 |
| 13 | - updated_at: 2026-05-10 |
| 14 | - author: agent (ANKB ingestion) |
| 15 | |
| 16 | ## Metadata |
| 17 | |
| 18 | - card_id: kb-javascript-ecmascript-and-modules-v1 |
| 19 | - world: software.javascript |
| 20 | - layer: world (L1 kb) |
| 21 | - tags: ecmascript, modules, esm, cjs, interop, engines (fundamentals) |
| 22 | - status: active |
| 23 | |
| 24 | ## Epistemic Linkage |
| 25 | |
| 26 | - epistemic_basis: fact + inference |
| 27 | - evidence_type: normative specification + de-facto platform behavior |
| 28 | - confidence: high для разделения ESM/CJS; medium для конкретных краёв interop между рантаймами |
| 29 | - transfer_boundary: не подменяет официальный **Import Maps** или bundler‑специфичные расширения — только языковой минимум и типовые ловушки |
| 30 | |
| 31 | ## Core Unit |
| 32 | |
| 33 | - **context:** проект объявляет целевые среды (браузер, Node, edge) и иногда **транспилятор** с полем `targets` / browserslist. |
| 34 | - **signal:** путаница «ES6 / ES2015 / ES2023», broken `require`/`import`, «заработало в браузере, упало под Node». |
| 35 | - **action:** зафиксировать **минимальную поддерживаемую матрицу**; для исходников — политику: нативный синтаксис vs только после сборки. |
| 36 | - **outcome:** предсказуемый граф модулей и отсутствие «магического» смешения семантик без явного shim. |
| 37 | - **lesson:** язык задаёт **синтаксис и семантику ESM**; упаковщик может эмулировать разрешение путей, но не отменяет отличий `this` и hoisting между системами. |
| 38 | |
| 39 | ### 1. ECMAScript как линия времени |
| 40 | |
| 41 | - **Fact:** стандарт развивается **ежегодными редакциями** (ES2015 как крупный рубеж для модулей, классов, стрелок, Promises и др.); коллоквиально «ES6» ≈ ES2015, но в инженерной переписке лучше **год**. |
| 42 | - **Heuristic:** называть фичу **по редакции**, в которой она стабилизирована в спецификации, и сверять с **matrix** браузера/Node (например через Baseline‑статусы или `compat`‑таблицы), а не по блогам. |
| 43 | - **First adoption task:** один источник правды на проект — `package.json` `engines`, browserslist или эквивалент. |
| 44 | - **Success criterion:** нет расхождения «учебник ES5» и «реальный код под ESM‑only». |
| 45 | - **Confidence:** high |
| 46 | |
| 47 | ### 2. ESM: статический импорт и живой биндинг |
| 48 | |
| 49 | - **Fact:** `import` на верхнем уровне модуля создаёт **живые read-only биндинги** к экспортам при условии, что экспортирующий модуль использует `let`/`const`/`class` с экспортом (модель в спецификации описывается через Module Record и Environment Records). |
| 50 | - **Heuristic:** циклические графы допустимы, но порядок инициализации чувствителен к тому, **где читается** ещё не проинициализированный биндинг (TDZ на уровне модуля для `let`/`const`). |
| 51 | - **First adoption task:** явно документировать шаблон безопасного re-export (`export { x } from './m.js'`). |
| 52 | - **Confidence:** high |
| 53 | |
| 54 | ### 3. Dynamic `import()` и разделение кода |
| 55 | |
| 56 | - **Fact:** `import(specifier)` возвращает Promise на namespace‑объект; доступность на верхнем уровне модулей и в async‑функциях следует правилам goal symbol `Module` в грамматике. |
| 57 | - **Heuristic:** загрузчик конкретной платформы всё равно может отказать по политике сети/CORS — это уже не язык. |
| 58 | - **Confidence:** high |
| 59 | |
| 60 | ### 4. CommonJS и interop под Node‑подобными рантаймами |
| 61 | |
| 62 | - **Fact:** `require`, `module.exports`, `exports` — **не часть ECMAScript**; это поверхность класса модульных систем до стандартизации ESM у платформы. Интероп (импорт CJS из ESM и обратно) **зависит от версии Node и флагов** (`package.json` `"type": "module"` резко меняет подразумеваемое расширение файлов и трактовку `.js`). |
| 63 | - **Heuristic:** новые библиотеки по возможности отдавать **чистый ESM** или явно документировать dual‑package hazards. |
| 64 | - **Falsification trigger:** код «работает локально под одним флагом» и ломается на CI без флага — проверить `type`, расширения `.cjs`/`.mjs`, условные экспорты `exports` в манифесте пакета. |
| 65 | - **Confidence:** medium (края пересмотреть при мажорных релизах Node) |
| 66 | |
| 67 | ### 5. `import.meta` и контекст модуля |
| 68 | |
| 69 | - **Fact:** `import.meta` — объект на уровне модуля с платформенно‑зависимыми полями (например `url` там, где определено). |
| 70 | - **Heuristic:** не подменять «путь файла» из CommonJS переменными `__filename` без адаптера — это разные модели окружения. |
| 71 | - **Confidence:** high |
| 72 | |
| 73 | ### 6. Транспиляция: зачем и где граница |
| 74 | |
| 75 | - **Fact:** транспилятор меняет **исходный** синтаксис в поддерживаемый целевыми движками AST/байткод; полифиллы добавляют **объекты времени выполнения** для новых API (не путать с синтаксисом). |
| 76 | - **Heuristic:** если цель — только синтаксис, но добавлены helper‑рантаймы (например для классов до полной нативной семантики), измерять **реальный выход**, а не «мы настроили preset env». |
| 77 | - **Confidence:** high |
| 78 | |
| 79 | ### 7. Реализации языка и хост-среды (fundamentals) |
| 80 | |
| 81 | - **Fact:** **V8** (Chromium, Node и др. встраивания), **SpiderMonkey** (Firefox), **JavaScriptCore** (Safari/WebKit) реализуют ECMAScript; **DOM и прочие host API** не входят в ECMA-262 как часть языка — это поверхность платформы. |
| 82 | - **Heuristic:** багфиксы и края (`Date`, `RegExp`, тайминги) могут различаться между движками — матрица CI и версии, не «работает у меня». |
| 83 | - **Operational follow-up:** lockfile, бандлеры, audit — слой **`kb-javascript-operational-ecosystem-v1.md`** после этого playbook. |
| 84 | - **Confidence:** high |
| 85 | |
| 86 | ## Lifecycle |
| 87 | |
| 88 | - supersedes: — |
| 89 | - superseded_by: — |
| 90 | - deprecation_reason: — |
| 91 | |