@rsconcept/rstool 0.5.1 → 0.6.0

package/examples/build-sample-rsmodel.ts

@@ -0,0 +1,106 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { CstType, RSToolWrapperClient, type AddOrUpdateConstituentaInput } from '../src';
+
+/** Tuple marker in structured values. */
+const TUPLE_ID = -111;
+
+async function run() {
+  const client = new RSToolWrapperClient({
+    cwd: resolve(process.cwd())
+  });
+
+  try {
+    await client.waitUntilReady();
+    const session = await client.call<{ sessionId: string; contractVersion: string }>('createSession');
+
+    const drafts: AddOrUpdateConstituentaInput[] = [
+      {
+        draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+      },
+      {
+        draft: { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }
+      },
+      {
+        draft: {
+          id: 3,
+          alias: 'S1',
+          cstType: CstType.STRUCTURED,
+          definitionFormal: 'ℬ(X1×X1)',
+          convention: 'Pairs (parent, child) over X1.'
+        }
+      },
+      {
+        draft: { id: 4, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
+      },
+      {
+        draft: { id: 5, alias: 'A1', cstType: CstType.AXIOM, definitionFormal: '1=1' }
+      }
+    ];
+
+    for (const input of drafts) {
+      const result = await client.call('addOrUpdateConstituenta', {
+        sessionId: session.sessionId,
+        input
+      });
+      console.log(
+        `Added ${input.draft.alias}:`,
+        (result as { diagnostics?: unknown[] }).diagnostics?.length ?? 0,
+        'diagnostics'
+      );
+    }
+
+    const model = await client.call('setConstituentaValues', {
+      sessionId: session.sessionId,
+      input: {
+        items: [
+          { target: 1, value: { 0: 'alice', 1: 'bob' } },
+          { target: 2, value: { 0: 'zero', 1: 'one', 2: 'two' } },
+          { target: 3, value: [[TUPLE_ID, 0, 1]] }
+        ]
+      }
+    });
+    console.log('Model values set:', model);
+
+    const d1Eval = await client.call('evaluateConstituenta', {
+      sessionId: session.sessionId,
+      input: { constituentId: 4 }
+    });
+    console.log('D1 (Pr1(S1)) evaluation:', d1Eval);
+
+    const a1Eval = await client.call('evaluateConstituenta', {
+      sessionId: session.sessionId,
+      input: { constituentId: 5 }
+    });
+    console.log('A1 (1=1) evaluation:', a1Eval);
+
+    const recalculated = await client.call('recalculateModel', {
+      sessionId: session.sessionId
+    });
+    const recalculatedItems = (recalculated as { items: { alias: string; status: number }[] }).items;
+    console.log(
+      'Recalculated model:',
+      recalculatedItems.map(item => ({ alias: item.alias, status: item.status }))
+    );
+
+    await client.call('commitStep', {
+      sessionId: session.sessionId,
+      message: 'Built sample RSModel'
+    });
+
+    const exported = await client.call<string>('exportSession', {
+      sessionId: session.sessionId
+    });
+    const outputPath = resolve(process.cwd(), 'examples', 'sample-rsmodel-session.json');
+    await writeFile(outputPath, exported, 'utf8');
+    console.log(`Sample RSModel exported: ${outputPath}`);
+  } finally {
+    await client.close();
+  }
+}
+
+run().catch(error => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/kinship/cli.ts

@@ -0,0 +1,247 @@
+import readline from 'node:readline/promises';
+import { resolve } from 'node:path';
+import { stdin as input, stdout as output } from 'node:process';
+
+import { RSToolWrapperClient } from '../../src';
+
+import { DEFAULT_SESSION_PATH } from './constants';
+import { KinshipModelSession } from './session';
+import {
+  formatS1,
+  formatX1,
+  formatA1Status,
+  genderLabel,
+  parseAddPersonArgs,
+  parseSetPersonArgs
+} from './x1-actions';
+
+const HELP = `
+Команды изменения X1 (люди):
+
+  list                         показать X1 и связи S1
+  add <м|ж> <имя>              добавить человека (пол: м, ж, m, f)
+  remove <имя>                 удалить человека (с пересчётом индексов и очисткой S1)
+  rename <старое> <новое>      переименовать
+  set <м|ж> <имя> ...         заменить X1 (пары пол+имя; S1 по именам)
+  set <имя1> <имя2> ...       то же, если пол уже известен из сессии / примера
+  clear                        очистить X1 и S1
+  save [путь]                  сохранить сессию (по умолчанию — исходный файл)
+  help                         эта справка
+  exit                         выход без сохранения
+
+Флаги запуска:
+  --session <path>             файл сессии (по умолчанию: ${DEFAULT_SESSION_PATH})
+  --no-save                    не сохранять после команды
+`.trim();
+
+const READONLY_COMMANDS = new Set(['help', '?', 'list', 'show']);
+
+function shouldAutoSave(command: string, autoSave: boolean): boolean {
+  return autoSave && command !== 'save' && !READONLY_COMMANDS.has(command);
+}
+
+interface CliOptions {
+  sessionPath: string;
+  autoSave: boolean;
+  command?: string;
+  args: string[];
+}
+
+function failCli(message: string): never {
+  console.error(message);
+  console.error('');
+  console.error(HELP);
+  process.exit(1);
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    sessionPath: DEFAULT_SESSION_PATH,
+    autoSave: true,
+    args: []
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--session') {
+      const value = argv[index + 1];
+      if (value === undefined) {
+        failCli('Ошибка: после --session требуется путь к файлу сессии.');
+      }
+      if (value.startsWith('-')) {
+        failCli(`Ошибка: недопустимое значение для --session: «${value}».`);
+      }
+      options.sessionPath = value;
+      index += 1;
+      continue;
+    }
+    if (token === '--no-save') {
+      options.autoSave = false;
+      continue;
+    }
+    if (!options.command) {
+      options.command = token;
+      continue;
+    }
+    options.args.push(token);
+  }
+
+  return options;
+}
+
+async function printModel(session: KinshipModelSession): Promise<void> {
+  const binding = await session.getX1Binding();
+  const s1 = await session.getS1Value();
+  const genderByName = session.getGenderByName();
+  console.log('X1 (люди):');
+  console.log(formatX1(binding, genderByName));
+  console.log('');
+  console.log(formatA1Status(binding));
+  console.log('');
+  console.log('S1 (родитель → ребёнок):');
+  console.log(formatS1(binding, s1));
+}
+
+async function runCommand(session: KinshipModelSession, command: string, args: string[]): Promise<boolean> {
+  switch (command) {
+    case 'help':
+    case '?':
+      console.log(HELP);
+      return true;
+
+    case 'list':
+    case 'show':
+      await printModel(session);
+      return true;
+
+    case 'add': {
+      const { gender, name } = parseAddPersonArgs(args);
+      await session.addPerson(name, gender);
+      await session.commitStep(`X1: добавлен «${name}» (${genderLabel(gender)})`);
+      console.log(`Добавлен: ${name} (${genderLabel(gender)})`);
+      await printModel(session);
+      return true;
+    }
+
+    case 'remove':
+    case 'rm': {
+      const name = args.join(' ').trim();
+      if (!name) {
+        throw new Error('Укажите имя: remove <имя>');
+      }
+      await session.removePerson(name);
+      await session.commitStep(`X1: удалён «${name}»`);
+      console.log(`Удалён: ${name}`);
+      await printModel(session);
+      return true;
+    }
+
+    case 'rename': {
+      const [oldName, ...rest] = args;
+      const newName = rest.join(' ').trim();
+      if (!oldName || !newName) {
+        throw new Error('Укажите имена: rename <старое> <новое>');
+      }
+      await session.renamePerson(oldName, newName);
+      await session.commitStep(`X1: «${oldName}» → «${newName}»`);
+      console.log(`Переименовано: ${oldName} → ${newName}`);
+      await printModel(session);
+      return true;
+    }
+
+    case 'set': {
+      const { specs } = parseSetPersonArgs(args, session.getGenderByName());
+      await session.setX1People(specs);
+      await session.commitStep(`X1: задан список (${specs.length})`);
+      const summary = specs.map(spec => `${spec.name} (${genderLabel(spec.gender)})`).join(', ');
+      console.log(`Задан X1: ${summary}`);
+      await printModel(session);
+      return true;
+    }
+
+    case 'clear': {
+      await session.clearX1();
+      await session.commitStep('X1 и S1 очищены');
+      console.log('X1 и S1 очищены');
+      await printModel(session);
+      return true;
+    }
+
+    case 'save': {
+      const savedPath = await session.save(args[0]);
+      console.log(`Сохранено: ${savedPath}`);
+      return true;
+    }
+
+    case 'exit':
+    case 'quit':
+      return false;
+
+    default:
+      throw new Error(`Неизвестная команда: ${command}\n\n${HELP}`);
+  }
+}
+
+async function runInteractive(session: KinshipModelSession, autoSave: boolean): Promise<void> {
+  const rl = readline.createInterface({ input, output });
+  console.log('Kinship model CLI — изменение X1');
+  console.log(`Сессия: ${resolve(process.cwd(), DEFAULT_SESSION_PATH)}`);
+  console.log('Введите help для списка команд.\n');
+
+  try {
+    for (;;) {
+      const line = (await rl.question('kinship> ')).trim();
+      if (!line) {
+        continue;
+      }
+      const [command, ...args] = line.split(/\s+/);
+      if (command === 'exit' || command === 'quit') {
+        break;
+      }
+      try {
+        await runCommand(session, command, args);
+        if (shouldAutoSave(command, autoSave)) {
+          const savedPath = await session.save();
+          console.log(`(автосохранение: ${savedPath})`);
+        }
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+      }
+      console.log('');
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  const client = new RSToolWrapperClient({ cwd: resolve(process.cwd()) });
+
+  try {
+    await client.waitUntilReady();
+    const session = await KinshipModelSession.open(client, options.sessionPath);
+
+    if (!options.command) {
+      await runInteractive(session, options.autoSave);
+      return;
+    }
+
+    const shouldContinue = await runCommand(session, options.command, options.args);
+    if (!shouldContinue) {
+      return;
+    }
+
+    if (shouldAutoSave(options.command, options.autoSave)) {
+      const savedPath = await session.save();
+      console.log(`Сохранено: ${savedPath}`);
+    }
+  } finally {
+    await client.close();
+  }
+}
+
+main().catch(error => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

package/examples/kinship/constants.ts

@@ -0,0 +1,12 @@
+/** Constituent ids in kinship RSForm / RSModel sessions. */
+export const X1_ID = 1;
+export const S1_ID = 2;
+export const S2_ID = 13;
+export const S3_ID = 14;
+export const D3_ID = 11;
+export const A1_ID = 12;
+
+/** Tuple marker in structured S1 values (frontend `TUPLE_ID`). */
+export const TUPLE_ID = -111;
+
+export const DEFAULT_SESSION_PATH = 'examples/kinship-rsmodel-session.json';

package/examples/kinship/session.ts

@@ -0,0 +1,190 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { type BasicBinding, type RSToolWrapperClient, type SessionModelState } from '../../src';
+
+import { S1_ID, S2_ID, S3_ID, X1_ID } from './constants';
+import {
+  addPerson,
+  type Gender,
+  type GenderRegistry,
+  genderByNameFromSets,
+  type S1Value,
+  removePerson,
+  renamePerson,
+  remapS1ByNames,
+  deriveGenderSets,
+  setX1WithGender
+} from './x1-actions';
+
+function asBinding(value: unknown): BasicBinding {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+  const binding: BasicBinding = {};
+  for (const [key, name] of Object.entries(value)) {
+    if (typeof name === 'string') {
+      binding[Number(key)] = name;
+    }
+  }
+  return binding;
+}
+
+function asS1Value(value: unknown): S1Value {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(item => Array.isArray(item)) as S1Value;
+}
+
+function asIndexList(value: unknown): number[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item): item is number => typeof item === 'number');
+}
+
+function getModelItem(model: SessionModelState, id: number): unknown {
+  return model.items.find(item => item.id === id)?.value ?? null;
+}
+
+export class KinshipModelSession {
+  private genderByName: GenderRegistry = {};
+
+  public constructor(
+    private readonly client: RSToolWrapperClient,
+    public readonly sessionId: string,
+    public readonly sessionPath: string
+  ) {}
+
+  public static async open(
+    client: RSToolWrapperClient,
+    sessionPath: string
+  ): Promise<KinshipModelSession> {
+    const absolutePath = resolve(process.cwd(), sessionPath);
+    const payload = await readFile(absolutePath, 'utf8');
+    const imported = await client.call<{ sessionId: string }>('importSession', { payload });
+    const session = new KinshipModelSession(client, imported.sessionId, absolutePath);
+    await session.loadGenderFromModel();
+    return session;
+  }
+
+  private async loadGenderFromModel(): Promise<void> {
+    const model = await this.getModelState();
+    const binding = asBinding(getModelItem(model, X1_ID));
+    const s2 = asIndexList(getModelItem(model, S2_ID));
+    const s3 = asIndexList(getModelItem(model, S3_ID));
+    this.genderByName = genderByNameFromSets(binding, s2, s3);
+  }
+
+  public getGenderByName(): Readonly<GenderRegistry> {
+    return this.genderByName;
+  }
+
+  public async getModelState(): Promise<SessionModelState> {
+    return this.client.call<SessionModelState>('getModelState', { sessionId: this.sessionId });
+  }
+
+  public async getX1Binding(): Promise<BasicBinding> {
+    const model = await this.getModelState();
+    return asBinding(getModelItem(model, X1_ID));
+  }
+
+  public async getS1Value(): Promise<S1Value> {
+    const model = await this.getModelState();
+    return asS1Value(getModelItem(model, S1_ID));
+  }
+
+  private async applyModelValues(binding: BasicBinding, s1: S1Value): Promise<SessionModelState> {
+    const { s2, s3 } = deriveGenderSets(binding, this.genderByName);
+    return this.client.call<SessionModelState>('setConstituentaValues', {
+      sessionId: this.sessionId,
+      input: {
+        items: [
+          { target: X1_ID, value: binding },
+          { target: S1_ID, value: s1 },
+          { target: S2_ID, value: s2 },
+          { target: S3_ID, value: s3 }
+        ]
+      }
+    });
+  }
+
+  private async clearModelValues(): Promise<SessionModelState> {
+    return this.client.call<SessionModelState>('clearConstituentaValues', {
+      sessionId: this.sessionId,
+      input: { items: [X1_ID, S1_ID, S2_ID, S3_ID] }
+    });
+  }
+
+  public async recalculateModel(): Promise<void> {
+    await this.client.call('recalculateModel', { sessionId: this.sessionId });
+  }
+
+  public async commitStep(message: string): Promise<void> {
+    await this.client.call('commitStep', { sessionId: this.sessionId, message });
+  }
+
+  public async save(outputPath = this.sessionPath): Promise<string> {
+    const exported = await this.client.call<string>('exportSession', { sessionId: this.sessionId });
+    const absolutePath = resolve(process.cwd(), outputPath);
+    await writeFile(absolutePath, exported, 'utf8');
+    return absolutePath;
+  }
+
+  public async addPerson(name: string, gender: Gender): Promise<{ binding: BasicBinding; s1: S1Value }> {
+    const binding = await this.getX1Binding();
+    const s1 = await this.getS1Value();
+    const nextBinding = addPerson(binding, name, gender, this.genderByName);
+    await this.applyModelValues(nextBinding, s1);
+    await this.recalculateModel();
+    return { binding: nextBinding, s1 };
+  }
+
+  public async removePerson(name: string): Promise<{ binding: BasicBinding; s1: S1Value }> {
+    const binding = await this.getX1Binding();
+    const s1 = await this.getS1Value();
+    const next = removePerson(binding, s1, name, this.genderByName);
+    await this.applyModelValues(next.binding, next.s1);
+    await this.recalculateModel();
+    return next;
+  }
+
+  public async renamePerson(oldName: string, newName: string): Promise<BasicBinding> {
+    const binding = await this.getX1Binding();
+    const nextBinding = renamePerson(binding, oldName, newName, this.genderByName);
+    const s1 = await this.getS1Value();
+    await this.applyModelValues(nextBinding, s1);
+    await this.recalculateModel();
+    return nextBinding;
+  }
+
+  public async setX1People(specs: { gender: Gender; name: string }[]): Promise<{
+    binding: BasicBinding;
+    s1: S1Value;
+  }> {
+    const oldBinding = await this.getX1Binding();
+    const s1 = await this.getS1Value();
+    const { binding: nextBinding, genderByName } = setX1WithGender(specs);
+    this.genderByName = genderByName;
+    const nextS1 = remapS1ByNames(oldBinding, nextBinding, s1);
+    await this.applyModelValues(nextBinding, nextS1);
+    await this.recalculateModel();
+    return { binding: nextBinding, s1: nextS1 };
+  }
+
+  public async clearX1(): Promise<void> {
+    this.genderByName = {};
+    await this.clearModelValues();
+    await this.recalculateModel();
+  }
+}
+
+export async function withKinshipSession<T>(
+  client: RSToolWrapperClient,
+  sessionPath: string,
+  action: (session: KinshipModelSession) => Promise<T>
+): Promise<T> {
+  const session = await KinshipModelSession.open(client, sessionPath);
+  return action(session);
+}

package/examples/kinship/x1-actions.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+
+import { TUPLE_ID } from './constants';
+import {
+  addPerson,
+  A1_MAX_PEOPLE,
+  deriveGenderSets,
+  formatX1,
+  parseAddPersonArgs,
+  parseGenderToken,
+  removePerson,
+  renamePerson,
+  remapS1ByNames,
+  setX1List,
+  setX1WithGender,
+  satisfiesA1MaxPeople,
+  x1Cardinality
+} from './x1-actions';
+
+const SAMPLE_BINDING = {
+  0: 'Иван',
+  1: 'Мария',
+  2: 'Пётр',
+  3: 'Анна'
+};
+
+const SAMPLE_S1 = [
+  [TUPLE_ID, 0, 2],
+  [TUPLE_ID, 1, 2],
+  [TUPLE_ID, 2, 3]
+];
+
+describe('kinship x1-actions', () => {
+  it('parses gender tokens', () => {
+    expect(parseGenderToken('м')).toBe('m');
+    expect(parseGenderToken('F')).toBe('f');
+    expect(parseGenderToken('unknown')).toBeNull();
+  });
+
+  it('parses add args as gender then name', () => {
+    expect(parseAddPersonArgs(['м', 'Олег'])).toEqual({ gender: 'm', name: 'Олег' });
+    expect(parseAddPersonArgs(['ж', 'Anna', 'Maria'])).toEqual({ gender: 'f', name: 'Anna Maria' });
+  });
+
+  it('adds person with next index and records gender', () => {
+    const genderByName: Record<string, 'm' | 'f'> = { Иван: 'm', Мария: 'f', Пётр: 'm', Анна: 'f' };
+    const next = addPerson(SAMPLE_BINDING, 'Олег', 'm', genderByName);
+    expect(next[4]).toBe('Олег');
+    expect(genderByName.Олег).toBe('m');
+    expect(formatX1(next, genderByName)).toContain('4: Олег (м)');
+    const { s2, s3 } = deriveGenderSets(next, genderByName);
+    expect(s2).toContain(4);
+    expect(s3).not.toContain(4);
+  });
+
+  it('renames person in place', () => {
+    const genderByName: Record<string, 'm' | 'f'> = { Иван: 'm', Мария: 'f', Пётр: 'm', Анна: 'f' };
+    const next = renamePerson(SAMPLE_BINDING, 'Пётр', 'Петр', genderByName);
+    expect(next[2]).toBe('Петр');
+    expect(genderByName.Петр).toBe('m');
+    expect(genderByName.Пётр).toBeUndefined();
+  });
+
+  it('rejects blank names on add and rename', () => {
+    const genderByName: Record<string, 'm' | 'f'> = {};
+    expect(() => addPerson(SAMPLE_BINDING, '   ', 'm', genderByName)).toThrow(/пустым/);
+    expect(() => parseAddPersonArgs(['м'])).toThrow(/пол и имя/);
+    expect(() => renamePerson(SAMPLE_BINDING, '   ', 'Петр', genderByName)).toThrow(/пустым/);
+    expect(() => renamePerson(SAMPLE_BINDING, 'Пётр', '   ', genderByName)).toThrow(/пустым/);
+  });
+
+  it('removes person and reindexes binding and S1', () => {
+    const genderByName: Record<string, 'm' | 'f'> = {
+      Иван: 'm',
+      Мария: 'f',
+      Пётр: 'm',
+      Анна: 'f'
+    };
+    const { binding, s1 } = removePerson(SAMPLE_BINDING, SAMPLE_S1, 'Мария', genderByName);
+    expect(binding).toEqual({ 0: 'Иван', 1: 'Пётр', 2: 'Анна' });
+    expect(s1).toEqual([
+      [TUPLE_ID, 0, 1],
+      [TUPLE_ID, 1, 2]
+    ]);
+    expect(genderByName.Мария).toBeUndefined();
+  });
+
+  it('sets X1 with explicit gender pairs', () => {
+    const { binding, genderByName } = setX1WithGender([
+      { gender: 'f', name: 'Анна' },
+      { gender: 'm', name: 'Иван' }
+    ]);
+    expect(binding).toEqual({ 0: 'Анна', 1: 'Иван' });
+    expect(deriveGenderSets(binding, genderByName)).toEqual({ s2: [1], s3: [0] });
+  });
+
+  it('replaces X1 list and remaps S1 by names', () => {
+    const nextBinding = setX1List(['Анна', 'Иван', 'Пётр']);
+    const nextS1 = remapS1ByNames(SAMPLE_BINDING, nextBinding, SAMPLE_S1);
+    expect(nextBinding).toEqual({ 0: 'Анна', 1: 'Иван', 2: 'Пётр' });
+    expect(nextS1).toEqual([
+      [TUPLE_ID, 1, 2],
+      [TUPLE_ID, 2, 0]
+    ]);
+  });
+
+  it('remaps S1 using actual binding indices, not list position', () => {
+    const sparseBinding = { 0: 'Иван', 5: 'Пётр', 9: 'Анна' };
+    const nextS1 = remapS1ByNames(SAMPLE_BINDING, sparseBinding, SAMPLE_S1);
+    expect(nextS1).toEqual([
+      [TUPLE_ID, 0, 5],
+      [TUPLE_ID, 5, 9]
+    ]);
+  });
+
+  it('rejects add when A1 would be violated', () => {
+    let binding: Record<number, string> = {};
+    const genderByName: Record<string, 'm' | 'f'> = {};
+    for (let index = 0; index < A1_MAX_PEOPLE; index += 1) {
+      binding = addPerson(binding, `P${index}`, index % 2 === 0 ? 'm' : 'f', genderByName);
+    }
+    expect(x1Cardinality(binding)).toBe(A1_MAX_PEOPLE);
+    expect(() => addPerson(binding, 'Лишний', 'm', genderByName)).toThrow(/A1/);
+  });
+
+  it('rejects set when A1 would be violated', () => {
+    const names = Array.from({ length: A1_MAX_PEOPLE + 1 }, (_, index) => `P${index}`);
+    expect(() => setX1List(names)).toThrow(/A1/);
+  });
+
+  it('allows binding at the A1 limit', () => {
+    const names = Array.from({ length: A1_MAX_PEOPLE }, (_, index) => `P${index}`);
+    const binding = setX1List(names);
+    expect(satisfiesA1MaxPeople(binding)).toBe(true);
+  });
+});