@rsconcept/rstool 0.5.1 → 0.6.0

package/README.md

@@ -78,7 +78,7 @@ From `rsconcept/rstool` (or run `powershell -File scripts/dev/LocalDevSetup.ps1`
 - `npm test`
 - `npm run build` — produce `dist/` via tsdown
 - `npm run wrapper` — dev stdio wrapper via `tsx`
-- `npm run example:client`, `npm run example:build-schema`, `npm run example:build-rsmodel`
+- `npm run example:client`, `npm run example:build-schema`, `npm run example:build-rsmodel` — see [`examples/README.md`](examples/README.md) for the full list (kinship scripts, session JSON)
 
 ## Stdio protocol
 

package/docs/CONCEPTUAL-SCHEMA.md

@@ -96,32 +96,3 @@ card(S1) = card(Pr1,2(S1))
 - `card(F[ξ]) = 1`.
 
 Перед `D{x∈… | ∃d1∈… ∃d2∈…}` проверь, нельзя ли взять `Pr` от уже введенного отношения.
-
-## Проверка на маленькой КМ
-
-Если семантика не очевидна, собери минимальную модель: значения для `X#`, `C#`, `S#`; затем вычисли целевые `D#`, `F#`, `P#`, `A#`.
-
-Особенно проверяй проекции, фильтры, `red`, `bool` / `debool`, аксиомы. Для важной проверки сделай скрипт-тест: сессия + значения неопределяемых конституент + проверка `success` и ожидаемого `value`.
-
-Цикл: `MODEL-TESTING.md`.
-
-## Быстрое ревью
-
-- Атрибутивная и родоструктурная экспликации не смешаны без запроса.
-- Нет проверки принадлежности к собственной типизации: `x∈X1` избыточно, если `x` уже объявлен в `X1`.
-- Покрыты главные сущности, роли, отношения, утверждения.
-- Повторяющиеся отборы вынесены в `F#`.
-- Каждая аксиома имеет понятную цель.
-- Сомнительная семантика проверена на маленькой КМ при наличии тестовых данных.
-
-## Рабочий порядок
-
-1. Собери словарь: базовые понятия, ключевые отношения, сценарий синтеза.
-2. Добавь `X#`, `C#` с конвенциями из источника.
-3. Добавь базовые `S#`: трансформация, перевод, допускание, выбор, цели, субъекты.
-4. Проверь, что базовые понятия независимы и не выводятся друг из друга.
-5. Добавь `A#` на структуры: `card`, покрытие `Pr1,2(S#)=…`, принадлежность выбора.
-6. Введи `F#` для типовых запросов.
-7. Производные понятия строй через `Pr*`, `Fi*`, `F#` от центрального `D#` и базовых `S#`.
-8. Перед каждым upsert запускай `analyzeExpression`.
-9. Для сомнительной семантики собери маленькую КМ (`MODEL-TESTING.md`).

package/docs/CONSTITUENTA.md

@@ -51,5 +51,3 @@
 3. Все глобальные ссылки уже есть в сессии.
 4. `axiom` и `statement` имеют типизацию `Logic`, иначе `expectedLogic`.
 5. Выводимая конституента с пустой формулой дает `cstEmptyDerived`.
-
-Цикл: `analyzeExpression` на черновике → исправить `diagnostics[].from/to` → `addOrUpdateConstituenta`.

package/docs/DIAGNOSTICS.md

@@ -78,8 +78,4 @@
 
 ## Цикл исправления
 
-1. Запусти `analyzeExpression`.
-2. Прочитай `code`, `from`, `to`, `params`.
-3. Исправь именно диапазон в `definitionFormal`.
-4. Не повторяй вызов без изменения ввода.
-5. После успеха вызывай `addOrUpdateConstituenta`.
+Пошаговый цикл — в `../skills/rstool-helper/GUIDE.md`, раздел «Цикл диагностик». Здесь — справочник кодов и типичных ошибок.

package/docs/MODEL-TESTING.md

@@ -11,15 +11,6 @@
 
 Для простой проверки типизации сначала используй `analyzeExpression`. КМ нужна, когда вопрос зависит от интерпретации данных и вычисленного значения.
 
-## Минимальный цикл
-
-1. Создай отдельную `createSession` или изолированную копию текущей сессии.
-2. Добавь только нужные поставщики: `X#`, `C#`, `S#` и проверяемые `D#` / `F#` / `P#` / `A#`.
-3. Проверь формулы через `analyzeExpression` и `addOrUpdateConstituenta`.
-4. Задай значения базовых понятий через `setConstituentaValue` или `setConstituentaValues`.
-5. Вычисли проверяемую формулу через `evaluateExpression` или сохраненную конституенту через `evaluateConstituenta`.
-6. Сравни результат с ожидаемым значением; если есть несколько зависимых определений, запусти `recalculateModel`.
-
 ## Что задавать руками
 
 `basic`, `constant`, `structure` можно интерпретировать напрямую. `term`, `function`, `predicate`, `axiom`, `statement` должны вычисляться из формулы, поэтому их напрямую не задавай.

package/docs/README.md

@@ -1,6 +1,8 @@
 # Документация rstool
 
-Краткая русская справка для агентов.
+Краткая справка для агентов.
+
+**Воркфлоу и чеклисты** — в `../skills/rstool-helper/GUIDE.md` (начинай с него). Здесь — справочные правила языка и предметной области.
 
 ## Какой файл читать
 
@@ -14,4 +16,4 @@
 - **PORTAL-API.md** — объекты REST API Portal.
 - **GRAMMAR-REF.md** — краткая карта токенов и приоритетов.
 
-Контракт агента `rstool` см. в `../skills/rstool-helper/REFERENCE.md`.
+Контракт агента `rstool` и примеры — `../skills/rstool-helper/REFERENCE.md`, `EXAMPLES.md` (на русском, вместе с `GUIDE.md`).

package/examples/README.md

@@ -0,0 +1,59 @@
+# Примеры rstool
+
+Полные исполняемые сценарии поверх `RSToolWrapperClient` (stdio-обёртка) и готовые JSON-сессии для импорта. Короткие фрагменты кода для агентов — в [`../skills/rstool-helper/EXAMPLES.md`](../skills/rstool-helper/EXAMPLES.md); воркфлоу — [`../skills/rstool-helper/GUIDE.md`](../skills/rstool-helper/GUIDE.md).
+
+## Как запускать
+
+**Из checkout репозитория** (`rsconcept/rstool`):
+
+```bash
+npm install
+npm run build          # обёртка для скриптов
+npm run example:client # и остальные example:* / kinship:cli — см. ниже
+```
+
+**После `npm install @rsconcept/rstool`** (нужен `tsx` или аналог):
+
+```bash
+npx tsx node_modules/@rsconcept/rstool/examples/agent-client.ts
+```
+
+Скрипты пишут JSON рядом с собой в `examples/`; запускайте из корня пакета (каталог, где лежит `package.json` rstool).
+
+## Скрипты
+
+| Файл | npm-скрипт | Назначение |
+|------|------------|------------|
+| [`agent-client.ts`](agent-client.ts) | `example:client` | Минимальный цикл: сессия, upsert, анализ, значения, диагностики через stdio |
+| [`build-sample-rsform.ts`](build-sample-rsform.ts) | `example:build-schema` | Собрать учебную RSForm (X1, S1, D1) и сохранить сессию |
+| [`build-sample-rsmodel.ts`](build-sample-rsmodel.ts) | `example:build-rsmodel` | RSForm + привязки + вычисления → учебная RSModel |
+| [`build-kinship-rsform.ts`](build-kinship-rsform.ts) | `example:build-kinship-schema` | Полная концептуальная схема «родственные отношения» (много конституент) |
+| [`build-kinship-rsmodel.ts`](build-kinship-rsmodel.ts) | `example:build-kinship-rsmodel` | Загрузить kinship RSForm, задать семью, вычислить модель (в т.ч. D3) |
+| [`kinship/cli.ts`](kinship/cli.ts) | `kinship:cli` | Интерактивное редактирование людей (X1) и связей (S1) в kinship-модели |
+
+## JSON-сессии
+
+Готовые снимки `exportSession` — для `importSession`, тестов и CLI:
+
+| Файл | Содержимое |
+|------|------------|
+| [`sample-rsform-session.json`](sample-rsform-session.json) | Учебная RSForm (результат `build-sample-rsform`) |
+| [`sample-rsmodel-session.json`](sample-rsmodel-session.json) | Учебная RSModel с вычисленными значениями |
+| [`kinship-rsform-session.json`](kinship-rsform-session.json) | Схема родства без привязок |
+| [`kinship-rsmodel-session.json`](kinship-rsmodel-session.json) | Kinship-модель с примерной семьёй (по умолчанию для `kinship:cli`) |
+
+Пересобрать JSON: соответствующий `build-*.ts` перезапишет файл в `examples/`.
+
+## Папка `kinship/`
+
+Вспомогательный код для сценария «родственные отношения», не отдельный пакет:
+
+| Файл | Роль |
+|------|------|
+| [`constants.ts`](kinship/constants.ts) | Id конституент (X1, S1, D3, A1, …) и путь сессии по умолчанию |
+| [`session.ts`](kinship/session.ts) | Обёртка над сессией: загрузка/сохранение, команды над X1 и S1 |
+| [`x1-actions.ts`](kinship/x1-actions.ts) | Парсинг и применение изменений списка людей |
+| [`x1-actions.test.ts`](kinship/x1-actions.test.ts) | Тесты логики X1 (`npm test`) |
+| [`cli.ts`](kinship/cli.ts) | REPL: `list`, `add`, `remove`, `rename`, `set`, `save`, … |
+
+См. также [`../docs/CONSTITUENTA.md`](../docs/CONSTITUENTA.md) (разбор kinship-схемы) и [`../docs/MODEL-TESTING.md`](../docs/MODEL-TESTING.md).

package/examples/agent-client.ts

@@ -0,0 +1,76 @@
+import { CstType, RSToolWrapperClient, type AddOrUpdateConstituentaInput, type AnalyzeExpressionInput } from '../src';
+
+interface CreateSessionResult {
+  sessionId: string;
+  contractVersion: string;
+}
+
+async function runExample() {
+  const client = new RSToolWrapperClient();
+  try {
+    await client.waitUntilReady();
+
+    const session = await client.call<CreateSessionResult>('createSession');
+    console.log('Session created:', session);
+
+    const baseInput: AddOrUpdateConstituentaInput = {
+      draft: {
+        id: 1,
+        alias: 'X1',
+        cstType: CstType.BASE,
+        definitionFormal: ''
+      }
+    };
+    await client.call('addOrUpdateConstituenta', {
+      sessionId: session.sessionId,
+      input: baseInput
+    });
+
+    const upsertInput: AddOrUpdateConstituentaInput = {
+      draft: {
+        id: 2,
+        alias: 'D1',
+        cstType: CstType.TERM,
+        definitionFormal: '1+2'
+      }
+    };
+    const upsert = await client.call('addOrUpdateConstituenta', {
+      sessionId: session.sessionId,
+      input: upsertInput
+    });
+    console.log('Upsert result:', upsert);
+
+    await client.call('setConstituentaValue', {
+      sessionId: session.sessionId,
+      input: { target: 1, value: { 0: 'zero', 1: 'one' } }
+    });
+
+    const evalResult = await client.call('evaluateConstituenta', {
+      sessionId: session.sessionId,
+      input: { constituentId: 2 }
+    });
+    console.log('Evaluation result:', evalResult);
+
+    const analyzeInput: AnalyzeExpressionInput = {
+      expression: '(',
+      cstType: CstType.TERM
+    };
+    const analysis = await client.call('analyzeExpression', {
+      sessionId: session.sessionId,
+      input: analyzeInput
+    });
+    console.log('Analysis result:', analysis);
+
+    const diagnostics = await client.call('listDiagnostics', {
+      sessionId: session.sessionId
+    });
+    console.log('Diagnostics count:', Array.isArray(diagnostics) ? diagnostics.length : diagnostics);
+  } finally {
+    await client.close();
+  }
+}
+
+runExample().catch(error => {
+  console.error(error);
+  process.exit(1);
+});