@reformer/builder-plugin-api 1.0.0-beta.1

package/dist/primitives/resource.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Ресурс — ССЫЛКА на нечто в источнике, а не его содержимое.
+ *
+ * В v1 дескриптор файла нёс на себе чтение и запись, был привязан к живому источнику и
+ * поэтому растёкся по стору, панелям, корпусу знаний и кодогену: любой, кто держал ссылку,
+ * держал и канал ввода-вывода. Здесь ресурс — описание, которое можно положить в стор,
+ * сериализовать и сравнить; чтение и запись живут в Workspace, который появится в Э2.
+ *
+ * Модуль владеет двумя вещами, которые нельзя отдавать адаптерам источников:
+ *
+ * - **нормализацией путей** — иначе два адаптера разойдутся в трактовке `..` и это вскроется
+ *   на третьем. Адаптеру остаётся смысл пути (что он адресует), а не его форма;
+ * - **таблицей расширений** — она решает ровно один вопрос: текст или байты (и подсветку).
+ *   Вопрос «что это за документ» здесь не решается вовсе: `.json` бывает и схемой формы,
+ *   и конфигом пакета, и как транспорт он однозначен в обоих случаях. Кто откроет файл —
+ *   решает редактор по успеху разбора.
+ *
+ * @module shell/platform/primitives/resource
+ */
+/**
+ * Непрозрачный идентификатор ресурса. Формат — `<sourceId>:<path>`.
+ *
+ * Сравнивать только целиком: у файловой системы внутри путь, у HTTP-источника — то,
+ * что вернул сервер, и потребитель не должен их различать. Разбирать идентификатор
+ * позволено только {@link parseResourceId} — и то потому, что путевая арифметика
+ * (резолвер импортов, дерево, листинг) без этого невозможна.
+ */
+export type ResourceId = string;
+/** Ссылка на ресурс: то, что можно хранить и передавать, не удерживая источник. */
+export interface ResourceRef {
+    readonly id: ResourceId;
+    readonly sourceId: string;
+    /** Путь внутри источника: разделитель `/`, без ведущего слэша, нормализован. */
+    readonly path: string;
+    /** Последний сегмент пути. Дублирует `path` намеренно — списки рисуют именно его. */
+    readonly name: string;
+    readonly kind: 'file' | 'directory';
+    /** `application/json`, `text/typescript`, `text/markdown`, `image/png`… */
+    readonly mediaType: string;
+}
+/**
+ * Свойства материализованного ресурса.
+ *
+ * Отдельно от {@link ResourceRef} по времени жизни: ссылка стабильна, а это — нет.
+ * Смешать их означало бы, что каждая перепроверка размера меняет объект, на который
+ * подписан UI.
+ */
+export interface ResourceStat {
+    readonly kind: 'file' | 'directory';
+    /**
+     * Непрозрачный маркер версии: ETag, mtime, хеш — что дал источник.
+     * Сравнивается ТОЛЬКО на равенство: «новее» вычислить нельзя, а конфликт — можно.
+     */
+    readonly revision?: string;
+    readonly size?: number;
+    readonly mediaType?: string;
+}
+/**
+ * Собирает идентификатор из источника и пути, попутно нормализуя путь.
+ *
+ * Нормализация здесь, а не у вызывающего: иначе `fs:./a` и `fs:a` окажутся разными ключами
+ * одного и того же ресурса, и кэш Workspace материализует его дважды.
+ *
+ * @throws если `sourceId` пуст или содержит `:` (разбор идёт по первому двоеточию,
+ *   и такой идентификатор нельзя было бы разобрать обратно), либо если путь выходит за корень.
+ */
+export declare function makeResourceId(sourceId: string, path: string): ResourceId;
+/**
+ * Разбирает идентификатор на источник и путь.
+ *
+ * Делит по ПЕРВОМУ двоеточию: `:` — легальный символ имени файла, а в `sourceId` он запрещён
+ * ({@link makeResourceId}), поэтому неоднозначности нет.
+ *
+ * Путь нормализуется и на разборе — идентификатор мог прийти извне (из хранилища, из ссылки,
+ * из ответа источника), и `fs:../../etc/hosts` обязан быть отвергнут здесь, а не в адаптере,
+ * где проверку легко забыть.
+ *
+ * @throws если строка не похожа на идентификатор ресурса или путь выходит за корень.
+ */
+export declare function parseResourceId(id: ResourceId): {
+    readonly sourceId: string;
+    readonly path: string;
+};
+/**
+ * Приводит путь к канонической форме: разделитель `/`, без ведущего и хвостового слэша,
+ * без пустых сегментов и `.`, с разрешёнными `..`.
+ *
+ * Корень источника — пустая строка: `''`, `'.'`, `'/'` дают один и тот же путь.
+ *
+ * @throws если `..` уводит выше корня источника. Это не педантизм: путь приходит из ответа
+ *   источника, из импорта внутри схемы и из ассистента, и молчаливое схлопывание такого
+ *   пути к корню превратило бы побег в обычное чтение.
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * Склеивает сегменты и нормализует результат.
+ *
+ * Это же и «резолв» для резолвера импортов: `joinPath(dirname(schema), './validation')`
+ * даёт путь соседа, а побег за корень отсекается нормализацией.
+ */
+export declare function joinPath(...segments: readonly string[]): string;
+/** Родительский каталог. Для ресурса верхнего уровня — корень источника, пустая строка. */
+export declare function dirname(path: string): string;
+/** Последний сегмент пути. Для корня — пустая строка. */
+export declare function basename(path: string): string;
+/**
+ * Расширение вместе с точкой (`.json`) или пустая строка.
+ *
+ * Ведущая точка — часть имени скрытого файла, а не расширение: у `.gitignore` расширения нет.
+ * Из `schema.d.ts` берётся только `.ts` — составные расширения таблица не различает, и это
+ * достаточно: `.d.ts` и `.ts` читаются одинаково.
+ */
+export declare function extname(path: string): string;
+/**
+ * Путь `to`, записанный относительно РЕСУРСА `from` — то есть относительно каталога,
+ * в котором `from` лежит.
+ *
+ * База — именно ресурс, а не каталог, потому что единственный потребитель — резолвер
+ * импортов, а импорт написан внутри файла: `../shared/rules` в `src/forms/credit/schema.json`
+ * означает `src/forms/shared/rules`.
+ *
+ * Результат всегда начинается с `./` или `..` — без префикса `shared/rules` читался бы
+ * как имя пакета, а не как сосед.
+ */
+export declare function relativePath(from: string, to: string): string;
+/**
+ * Расширение → медиатип. Таблица отвечает на один вопрос: текст или байты (и какая подсветка).
+ *
+ * Она сознательно не полна и не должна расти «на всякий случай»: неизвестное расширение —
+ * это {@link DEFAULT_MEDIA_TYPE}, и источник всё равно может переопределить ответ.
+ */
+export declare const MEDIA_TYPE_BY_EXTENSION: Readonly<Record<string, string | undefined>>;
+/**
+ * Ответ для неизвестного расширения.
+ *
+ * Текст, а не `application/octet-stream`: файлы без узнаваемого расширения — это `LICENSE`,
+ * `.editorconfig`, `.prettierrc` и прочие конфиги, то есть текст, а бинарные форматы как раз
+ * всегда носят расширение из таблицы. Обратный выбор запретил бы `readText` там, где он нужен
+ * чаще всего.
+ */
+export declare const DEFAULT_MEDIA_TYPE = "text/plain";
+/**
+ * Медиатип ресурса: основа — расширение, подсказка источника имеет приоритет.
+ *
+ * Приоритет именно такой, потому что источник знает больше: `Content-Type` HTTP-ответа —
+ * это факт о содержимом, а расширение — догадка по имени. Нераспознаваемая подсказка
+ * игнорируется, и ответ падает обратно на таблицу.
+ *
+ * @param path путь ресурса; для {@link ResourceRef} — его `path`.
+ * @param hint то, что сказал источник (заголовок `Content-Type` или его аналог).
+ */
+export declare function mediaTypeFor(path: string, hint?: string): string;
+/**
+ * Можно ли читать такой ресурс текстом.
+ *
+ * Единственный вопрос, на который отвечает медиатип в контуре чтения: `readText` бинарного
+ * ресурса обязан быть отказом, а не набором мусорных символов — тихая порча данных хуже отказа.
+ */
+export declare function isTextMediaType(mediaType: string): boolean;

package/dist/primitives/semver.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Версии и диапазоны — ровно в том объёме, в каком их спрашивает манифест плагина.
+ *
+ * ## Решение: своя утилита, а не пакет `semver`
+ *
+ * Пакета `semver` в зависимостях нет, и заводить его ради трёх сравнений мы не стали. Довод
+ * не «лишняя зависимость вообще», а измеримый: библиотека едет в БРАУЗЕРНЫЙ бандл оболочки,
+ * потому что диапазон разбирается при обходе каталога плагинов, то есть в рантайме, — и платит
+ * за это каждый, кто открыл инструмент, включая тех, у кого плагинов нет вовсе. Взамен мы
+ * обязаны назвать, чего эта утилита НЕ умеет: список ниже и есть цена решения.
+ *
+ * ## Чего здесь нет — названо, а не забыто
+ *
+ * - **Пререлизы (`1.0.0-beta.1`) отвергаются.** Не «игнорируются»: {@link parseVersion}
+ *   и {@link parseRange} возвращают `undefined`, а разбор манифеста превращает это в отказ
+ *   с внятным текстом. Молчаливое отбрасывание суффикса дало бы худший из возможных исходов —
+ *   плагин, объявивший `^1.0.0-beta`, работал бы против релизного API и узнал бы об этом
+ *   поведением, а не сообщением.
+ * - **Составных диапазонов нет.** Ни конъюнкции (`>=1.2.0 <2.0.0`), ни дизъюнкции (`1.x || 2.x`).
+ *   Один сравнитель на диапазон — всё остальное отвергается разбором. Требование плагина,
+ *   которое нельзя выразить каретой или тильдой, почти наверняка означает, что контракт
+ *   пора делить на два, а не что нам нужна грамматика npm.
+ * - **Метаданных сборки (`+build`) нет** — по той же причине, что и пререлизов.
+ *
+ * ## Отступление от npm, которое стоит знать
+ *
+ * У npm неполная версия при сравнителе округляется вверх: `>1.2` там значит `>=1.3.0`. Здесь
+ * недостающие части заполняются нулями, и `>1.2` значит `>1.2.0`. Правило npm сюрпризно ровно
+ * в том месте, где человек пишет диапазон руками в JSON, — а заполнение нулями читается
+ * одинаково всеми. Всё остальное (карета на нулевом мажоре, тильда, X-диапазоны) совпадает
+ * с npm намеренно: автор плагина приносит привычку из `package.json`.
+ *
+ * @module shell/platform/primitives/semver
+ */
+/** Разобранная версия. Три числа и ничего больше — см. «чего здесь нет» в шапке модуля. */
+export interface SemVer {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+}
+/** Граница диапазона: версия плюс то, входит ли она сама. */
+export interface VersionBound {
+    readonly version: SemVer;
+    readonly inclusive: boolean;
+}
+/**
+ * Разобранный диапазон — ВСЕГДА в виде пары границ, какой бы формой он ни был записан.
+ *
+ * Нормализация к границам, а не хранение сравнителя, нужна ради одного: `satisfies` тогда
+ * не ветвится по форме записи вовсе. Карета, тильда и X-диапазон отличаются только тем,
+ * как из них считается верхняя граница, и это различие обязано жить в разборе, а не в каждой
+ * проверке.
+ *
+ * `source` сохраняется дословно: его показывают человеку в отказе, и `^1` там обязан выглядеть
+ * как `^1`, а не как «>=1.0.0 <2.0.0», которого он не писал.
+ */
+export interface VersionRange {
+    readonly source: string;
+    /** Нижняя граница. Её нет только у `*`. */
+    readonly min?: VersionBound;
+    /** Верхняя граница. Её нет у `>=`, `>` и `*`. */
+    readonly max?: VersionBound;
+}
+/**
+ * Разбирает версию: `1.2.3`, `1.2`, `1`.
+ *
+ * Неполная версия дополняется нулями — `1.2` это `1.2.0`. Пререлиз и метаданные сборки
+ * отвергаются (см. шапку модуля), поэтому `undefined` здесь значит «так версия не пишется»,
+ * а не «версия старая».
+ */
+export declare function parseVersion(text: string): SemVer | undefined;
+/** `1.2.3` — для сообщений об отказе и для сравнения строк в тестах. */
+export declare function formatVersion(version: SemVer): string;
+/** Обычный порядок: отрицательное — `a` раньше `b`. */
+export declare function compareVersions(a: SemVer, b: SemVer): number;
+/**
+ * Разбирает диапазон: `^1`, `~1.2`, `>=1.2.3`, `>1`, `<=2.0.0`, `<2`, `1.2.3`, `1.x`, `*`.
+ *
+ * `undefined` — диапазон не той формы: составной (`>=1 <2`, `1.x || 2.x`), с пререлизом,
+ * с лишними компонентами. Разбор манифеста превращает это в отказ, а не в «пропустим».
+ */
+export declare function parseRange(text: string): VersionRange | undefined;
+/** Попадает ли версия в диапазон. Обе стороны уже разобраны — отказов здесь не бывает. */
+export declare function satisfiesRange(version: SemVer, range: VersionRange): boolean;
+/**
+ * Удобная форма для вызывающего, которому нечего делать с разбором: строка против строки.
+ *
+ * Неразбираемая сторона даёт `false`, а не исключение, — но именно поэтому проверять ФОРМУ
+ * записи этой функцией нельзя: «не та версия» и «так версия не пишется» здесь неразличимы.
+ * Там, где различие нужно (разбор манифеста), зовут {@link parseVersion} и {@link parseRange}
+ * по отдельности.
+ */
+export declare function satisfies(version: string, range: string): boolean;

package/dist/primitives/service.d.ts

@@ -0,0 +1,68 @@
+import { Disposable } from './disposable.js';
+/**
+ * Типизированная ссылка на сервис.
+ *
+ * Сравнивается и хранится **по `id`**, а не по идентичности объекта. Это осознанно:
+ * плагины из каталога проекта грузятся собственным линкером, и один и тот же модуль
+ * с объявлением токена может оказаться в памяти дважды. При ключе по объекту второй
+ * экземпляр токена не нашёл бы уже зарегистрированный сервис, а диагностика выглядела бы
+ * как «сервис есть, но не находится» — худший вид отказа.
+ */
+export interface ServiceToken<T> {
+    readonly id: string;
+    /**
+     * Только для вывода типов, в рантайме поля нет.
+     *
+     * Без него `ServiceToken<A>` и `ServiceToken<B>` структурно одинаковы, и компилятор
+     * молча пропустил бы `register(tokenA, implB)`.
+     */
+    readonly __type?: T;
+}
+/**
+ * Объявляет токен сервиса.
+ *
+ * `id` попадает в сообщения об ошибках и в ключ реестра, поэтому он обязан быть
+ * непустым и осмысленным: `reformer.workspace`, а не `ws`.
+ */
+export declare function defineService<T>(id: string): ServiceToken<T>;
+/**
+ * Слот занят или освобождён.
+ *
+ * Нагрузка — только идентификатор и факт: реализацию подписчик берёт `get`, потому что между
+ * уведомлением и чтением слот мог смениться ещё раз, и переданная в событии ссылка была бы
+ * устаревшей ровно в том сценарии, ради которого уведомление и заведено (перезагрузка плагина
+ * снимает регистрацию и ставит новую).
+ */
+export interface ServiceChange {
+    readonly id: string;
+    /** `true` — слот занят, `false` — освобождён. */
+    readonly present: boolean;
+}
+export interface ServiceRegistry {
+    /**
+     * Занимает слот токена.
+     *
+     * Бросает, если слот уже занят: действующая реализация иначе зависела бы от порядка
+     * активации, а он объявлен незначимым. `dispose()` освобождает слот — после него токен
+     * снова можно зарегистрировать.
+     */
+    register<T>(token: ServiceToken<T>, impl: T): Disposable;
+    /** `undefined`, если сервиса нет. Вызывающий обязан деградировать, а не падать. */
+    get<T>(token: ServiceToken<T>): T | undefined;
+    /** Бросает с внятным сообщением. Только для сервисов Host — см. правило доступности. */
+    require<T>(token: ServiceToken<T>): T;
+    /**
+     * Слот заняли или освободили.
+     *
+     * Заведено для одного проверяемого случая: **наблюдать за появлением провайдера нечем**.
+     * Правило «сервис ищется в момент использования» закрывает команды и обработчики — они
+     * спрашивают реестр тогда, когда их позвали, — но не закрывает того, кто обязан ОТРЕАГИРОВАТЬ
+     * на появление службы: перерисовать панель, доставшую наконец своего провайдера, или снять
+     * деградацию. Без уведомления такому потребителю остаётся опрос по таймеру.
+     *
+     * Подписчик не должен полагаться на порядок и обязан быть дешёвым: доставка синхронная,
+     * внутри `register`/`dispose`. Его исключение не выходит наружу — оно бы превратило отказ
+     * наблюдателя в отказ регистрации, то есть уронило бы активацию чужого плагина.
+     */
+    onDidChange(listener: (event: ServiceChange) => void): Disposable;
+}

package/dist/primitives/when-context.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Контекст применимости — снимок состояния, по которому команда решает, доступна ли она сейчас.
+ *
+ * Проектируется раньше реестра, и это не порядок изложения. Вторая причина монолитности
+ * обработчика клавиш в v1 — охранные условия («фокус в поле ввода», «курсор на канвасе»,
+ * «не на кнопке»). Реестр команд сам по себе их не убирает, он их прячет: условия просто
+ * переезжают внутрь десятка `enabled`. Убирает их только явный снимок состояния, общий для
+ * всех команд, — вот этот.
+ *
+ * Почему сюда входит режим превью: условие «курсор на канвасе» невозможно выразить, не
+ * обращаясь одновременно к режиму поверхности. Проверка по коду v1 дала отрицательный ответ,
+ * поэтому режим входит в контекст сразу — иначе контракт пришлось бы ломать на первом же
+ * редакторе.
+ *
+ * Ни одно поле не знает предметной области: `activeResourceKind` и `previewMode` —
+ * непрозрачные строки, их смысл задаёт плагин, Host только переносит значение от источника
+ * к предикату.
+ *
+ * @module shell/platform/primitives/when-context
+ */
+/**
+ * Куда направлен фокус.
+ *
+ * Различение `editable` от остальных несущее: именно на нём стоит правило «сочетание
+ * пропускается, если фокус в поле ввода» — то самое, из-за которого v1 не разбирается на части.
+ *
+ * - `editable` — поле ввода, текстовый редактор, `contenteditable`;
+ * - `canvas` — поверхность превью;
+ * - `tree` — дерево ресурсов;
+ * - `panel` — прочий интерфейс оболочки;
+ * - `none` — фокуса нет ни на чём осмысленном (например, на `body`).
+ */
+export type FocusTarget = 'editable' | 'control' | 'canvas' | 'tree' | 'panel' | 'none';
+/** Состояние, в котором вычисляется применимость команды. Только чтение, только снимок. */
+export interface WhenContext {
+    /** Куда направлен фокус: поле ввода, канвас, дерево, панель. */
+    readonly focus: FocusTarget;
+    /** Идентификатор активного редактора; `null`, если открытых вкладок нет. */
+    readonly activeEditorId: string | null;
+    /**
+     * Вид активного ресурса — непрозрачная строка от плагина документа
+     * (`form.schema`, `markdown`, …). Host её не интерпретирует, только сравнивает.
+     */
+    readonly activeResourceKind: string | null;
+    /** Есть ли выделение — в дереве, на канвасе или в редакторе; что именно, знает редактор. */
+    readonly hasSelection: boolean;
+    /**
+     * Режим поверхности превью; `null` — превью не активно.
+     *
+     * Без этого поля не выражается «курсор на канвасе»: одного `focus === 'canvas'` мало,
+     * потому что в режиме взаимодействия тот же фокус означает противоположное.
+     */
+    readonly previewMode: string | null;
+}
+/**
+ * Нейтральный контекст: ничего не в фокусе, ничего не открыто, ничего не выделено.
+ *
+ * Нужен там, где реального контекста ещё нет: реестр команд без поставщика контекста,
+ * тесты, вызов команды из кода при старте. Значение заморожено — им можно делиться.
+ */
+export declare const NEUTRAL_WHEN_CONTEXT: WhenContext;
+/**
+ * Собирает контекст из нейтрального и переданных отличий.
+ *
+ * Существует ради одного свойства: добавление поля в {@link WhenContext} не должно ломать
+ * каждое место, где контекст собирается. Поставщики контекста в оболочке и тесты указывают
+ * только то, что для них значимо.
+ */
+export declare function whenContext(patch?: Partial<WhenContext>): WhenContext;

package/dist/primitives/when-expr.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Условие применимости как ДАННЫЕ: разбор, вычисление, специфичность.
+ *
+ * ## Зачем понадобилось, если есть `enabled(ctx)`
+ *
+ * Предикат отвечает на вопрос «доступна ли команда сейчас» и больше ни на какой. Всё
+ * остальное, что нужно клавиатуре, требует условие ПРОЧИТАТЬ, а функцию прочитать нельзя:
+ *
+ * - **сравнить два условия** — без этого нельзя решить, чья клавиша выигрывает, и `delete`
+ *   в проекте сегодня разводится порядком регистрации плагинов, который по контракту
+ *   ничего не значит (см. `plugin/registry.test.ts`);
+ * - **доказать, что два условия не пересекаются** — без этого всякая пара на одной клавише
+ *   выглядит конфликтом, даже «в дереве» против «на канвасе»;
+ * - **записать в файл** — манифест плагина и раскладка пользователя это текст;
+ * - **показать человеку** — в таблице клавиш условие обязано быть видно, иначе строка
+ *   «Delete — удалить» повторяется дважды и объяснить разницу нечем.
+ *
+ * Поэтому условие становится строкой с грамматикой, а `enabled` остаётся — они отвечают
+ * на разные вопросы. Водораздел проведён в шапке `./command`: `when` — про состояние
+ * платформы (где фокус, что открыто), `enabled` — про приватное состояние владельца
+ * (есть ли что отменять). Второе данными быть не может и переводу не подлежит.
+ *
+ * ## Чего в грамматике нет
+ *
+ * Арифметики, вызовов, присваивания. Ограничение не про аскетизм: специфичность считается
+ * обходом дерева, и как только в условии появится вычисление, она перестанет быть
+ * определимой — а вместе с ней и правило «кто выигрывает».
+ *
+ * ## Отношение к платформе и DOM
+ *
+ * Никакого. Модуль лежит в `primitives` рядом с `normalizeKeybinding` и по той же причине:
+ * его зовут двое — реестр команд (проверка на регистрации) и диспетчер клавиш (вычисление
+ * на нажатии), а `primitives` не имеет права импортировать `ui`.
+ *
+ * @module shell/platform/primitives/when-expr
+ */
+/** Значение в правой части сравнения. Только литерал — см. {@link parseWhen}. */
+export type WhenLiteral = string | number | boolean | null;
+/**
+ * Узел разобранного условия.
+ *
+ * `negated` полем, а не обёрткой `not`, у сравнений — несущее решение: `a != b` и `!(a == b)`
+ * обязаны давать ОДНУ структуру. Разойдись они, два одинаковых по смыслу правила получили бы
+ * разную специфичность, по-разному участвовали бы в разрешении конфликта и выглядели бы
+ * разными в редакторе клавиш — при том, что человек написал одно и то же.
+ */
+export type WhenNode = {
+    readonly kind: 'true';
+} | {
+    readonly kind: 'key';
+    readonly key: string;
+} | {
+    readonly kind: 'not';
+    readonly operand: WhenNode;
+} | {
+    readonly kind: 'and';
+    readonly operands: readonly WhenNode[];
+} | {
+    readonly kind: 'or';
+    readonly operands: readonly WhenNode[];
+} | {
+    readonly kind: 'eq';
+    readonly key: string;
+    readonly value: WhenLiteral;
+    readonly negated: boolean;
+} | {
+    readonly kind: 'match';
+    readonly key: string;
+    readonly pattern: string;
+    readonly flags: string;
+    readonly negated: boolean;
+} | {
+    readonly kind: 'in';
+    readonly key: string;
+    readonly collection: string;
+    readonly negated: boolean;
+};
+/** Разобранное условие вместе со всем, что выводится из него один раз. */
+export interface WhenExpr {
+    /** Как написано человеком. Показывается в редакторе клавиш и в диагностике. */
+    readonly source: string;
+    readonly ast: WhenNode;
+    /**
+     * Ключи, которые условие ЧИТАЕТ, отсортированные и без повторов. Включает правую часть
+     * `in`: по этому набору подписываются на изменения контекста и по нему же считается
+     * диагностика «условие ссылается на ключ, которого никто не объявил».
+     */
+    readonly keys: readonly string[];
+    /** Насколько узко условие называет место. Считается при разборе — см. {@link whenSpecificity}. */
+    readonly specificity: number;
+}
+/**
+ * Отказ разбора. Не `CommandError` намеренно: тот живёт в `./command`, который импортирует
+ * этот модуль, и обратная ссылка замкнула бы цикл. Реестр команд ловит эту ошибку и
+ * заворачивает в свой `CommandError('invalid-when')` — там, где у отказа появляется
+ * идентификатор команды.
+ */
+export declare class WhenSyntaxError extends Error {
+    /** Смещение в исходной строке — редактор подсветит место, а не всю строку. */
+    readonly at: number;
+    readonly source: string;
+    constructor(message: string, source: string, at: number);
+}
+export interface WhenParseError {
+    readonly message: string;
+    readonly at: number;
+    readonly source: string;
+}
+export type WhenParseResult = {
+    readonly ok: true;
+    readonly expr: WhenExpr;
+} | {
+    readonly ok: false;
+    readonly error: WhenParseError;
+};
+/**
+ * Насколько узко условие называет место. Больше — уже, значит выигрывает при равном слое.
+ *
+ * Правила и их обоснование:
+ *
+ * - **дизъюнкция берёт МИНИМУМ ветвей.** Условие, истинное в объединении состояний,
+ *   ограничивает ровно настолько, насколько его слабейшая ветвь. Возьми мы максимум —
+ *   условие с приставкой «или всегда» встало бы ВЫШЕ исходного, совпадая при этом со строго
+ *   большим числом состояний, и приписка стала бы способом перебить кого угодно. Правило,
+ *   срабатывающее чаще, не имеет права выигрывать у срабатывающего реже.
+ * - **конъюнкция — сумма:** каждый конъюнкт сужает.
+ * - **отрицание — тождество:** отрицание ограничивает дополнением, то есть той же силы.
+ *   Обнули мы его — «работает, когда ничего не выделено» стало бы безусловным.
+ * - **сравнение дороже проверки на истинность на единицу:** сравнение выбирает одно значение
+ *   из открытого множества, а голый ключ делит мир пополам.
+ */
+export declare function whenSpecificity(ast: WhenNode): number;
+/** Все читаемые ключи, отсортированные и без повторов. */
+export declare function whenKeys(ast: WhenNode): readonly string[];
+/**
+ * Вычисляет условие по читателю ключей.
+ *
+ * Читатель, а не снимок `WhenContext`: областей и ключей плагинов в контексте из пяти полей
+ * нет, и тип с пятью полями заставил бы их туда положить — то есть расширять контракт на
+ * каждый ключ, который завёл чужой плагин.
+ *
+ * **Неизвестный ключ — ложь, а не отказ.** Условие вправе ссылаться на ключ выключенного
+ * плагина: это нормальное состояние приложения, а не поломка. Правило при этом просто
+ * перестаёт совпадать, и клавиша достаётся следующему кандидату.
+ */
+export declare function evaluateWhen(expr: WhenExpr, read: (key: string) => unknown): boolean;
+/** Условие «всегда». Пустая строка и отсутствие условия дают именно его. */
+export declare const WHEN_TRUE: WhenExpr;
+/**
+ * Разбирает условие, бросая {@link WhenSyntaxError}. Для кода: объявление команды проверяется
+ * НА РЕГИСТРАЦИИ — по тому же доводу, что и сочетание клавиш (см. `./command`), — иначе
+ * опечатка живёт до того дня, когда кто-то попробует нажать клавишу.
+ */
+export declare function compileWhen(source: string): WhenExpr;
+/**
+ * Разбирает условие, НЕ бросая. Для всего, что человек правит руками: манифест плагина,
+ * раскладка пользователя. Испорченная запись в файле — обычное состояние, а не авария,
+ * и ронять на ней загрузку нельзя.
+ */
+export declare function parseWhen(source: string): WhenParseResult;
+/**
+ * Доказуемо ли, что два условия НЕ МОГУТ быть истинны одновременно.
+ *
+ * Осознанно неполна и доказывает ровно один случай: сравнение ОДНОГО ключа с РАЗНЫМИ
+ * литералами (фокус в дереве против фокуса на канвасе). Всё остальное считается
+ * пересекающимся.
+ *
+ * Полная проверка непересекаемости для произвольной булевой формулы над открытым множеством
+ * значений в общем виде неразрешима, а приближать её эвристиками здесь нельзя: цена ошибки
+ * несимметрична. Не доказали непересекаемость там, где она есть, — человек увидит лишнее
+ * предупреждение в редакторе клавиш. «Доказали» там, где её нет, — конфликт молча пропущен,
+ * и одна из двух клавиш не работает без единого следа.
+ *
+ * Ровно этот один случай закрывает то, ради чего функция и заводится: пара `delete` в дереве
+ * против `delete` на канвасе.
+ */
+export declare function provablyDisjoint(a: WhenExpr, b: WhenExpr): boolean;