@rsconcept/rstool 0.10.3 → 1.0.1

package/src/index.ts

@@ -1,9 +1,10 @@
-export {
-  toPublicAnalysis,
-  toPublicError,
-  type DomainAnalysisLike,
-  type DomainErrorLike
-} from './mappers/types';
+/**
+ * Public API for `@rsconcept/rstool`.
+ *
+ * Primary entry points: {@link RSToolAgent} (in-process) and {@link RSToolWrapperClient}
+ * (stdio child process). Types describe the v2 agent contract.
+ */
+export { toPublicAnalysis, toPublicError, type DomainAnalysisLike, type DomainErrorLike } from './mappers/types';
 export {
   CONTRACT_VERSION,
   CstType,
@@ -11,39 +12,45 @@ export {
   RSErrorCode,
   RSToolAgent,
   ValueClass,
-  type AddOrUpdateConstituentaInput,
-  type AddOrUpdateConstituentaResult,
+  type AgentConstituentaPatch,
   type AnalysisResult,
   type AnalyzeExpressionInput,
+  type ApplySchemaPatchInput,
+  type ApplySchemaPatchResult,
   type BasicBinding,
-  type ClearConstituentaValuesInput,
   type ConstituentaDraft,
   type ConstituentaState,
   type DiagnosticRecord,
-  type EvaluateConstituentaInput,
-  type EvaluateExpressionInput,
+  type EvaluateInput,
   type EvaluationResult,
+  type ExportFormat,
+  type ExportPortalInput,
+  type ExportPortalResult,
+  type ImportDataKind,
   type ListDiagnosticsFilters,
   type ModelValueState,
   PORTAL_JSON_CONTRACT_VERSION,
+  type PortalExportKind,
   type PortalImportMetadata,
   type PortalModelImportData,
+  type PortalRsformDetails,
   type PortalSchemaConstituenta,
   type PortalSchemaImportData,
   type PortalTermForm,
   type RecalculateModelResult,
   type RSToolAgentContract,
+  type RSToolAgentOptions,
   type RSToolErrorDescription,
   type RSToolValue,
   type SessionHandle,
   type SessionModelState,
   type SessionRevision,
+  type SessionStateDetail,
+  type SessionStateResult,
+  type SessionSummary,
+  type SessionSummaryItem,
   type SessionState,
   type SetConstituentaValueInput,
-  type SetConstituentaValuesInput
+  type SetModelValuesInput
 } from './models';
-export {
-  RSToolWrapperClient,
-  type RSToolWrapperClientOptions,
-  type WrapperResponse
-} from './wrapper/client';
+export { RSToolWrapperClient, type RSToolWrapperClientOptions, type WrapperResponse } from './wrapper/client';

package/src/mappers/portal-adapter.ts

@@ -0,0 +1,49 @@
+import { type ConstituentaDraft } from '../models/constituenta';
+import {
+  type PortalImportMetadata,
+  type PortalRsformDetails,
+  type PortalSchemaImportData,
+  portalItemToDraft
+} from '../models/portal-json';
+import { type SessionState } from '../models/session';
+
+type PortalSessionSeedInput = Partial<Pick<PortalImportMetadata, 'alias' | 'title' | 'description'>>;
+
+function portalMetadataToSessionSeed(data: PortalSessionSeedInput): Partial<SessionState> {
+  return {
+    alias: data.alias ?? '',
+    title: data.title ?? '',
+    comment: data.description ?? '',
+    items: []
+  };
+}
+
+export function portalSchemaToSessionSeed(data: PortalSchemaImportData): Partial<SessionState> {
+  return portalMetadataToSessionSeed(data);
+}
+
+export function portalDetailsToSessionSeed(data: PortalRsformDetails): Partial<SessionState> {
+  return portalMetadataToSessionSeed(data);
+}
+
+export function portalItemsToDrafts(
+  items: Array<{
+    id: number;
+    alias: string;
+    cst_type: string;
+    definition_formal?: string;
+    term_raw?: string;
+    definition_raw?: string;
+    convention?: string;
+  }>
+): ConstituentaDraft[] {
+  return items.map(item => portalItemToDraft(item));
+}
+
+export function portalSchemaToDrafts(data: PortalSchemaImportData): ConstituentaDraft[] {
+  return portalItemsToDrafts(data.items);
+}
+
+export function portalDetailsToDrafts(data: PortalRsformDetails): ConstituentaDraft[] {
+  return portalItemsToDrafts(data.items);
+}

package/src/mappers/types.ts

@@ -2,6 +2,7 @@ import { type ValueClass } from '@rsconcept/domain/rslang';
 
 import { type AnalysisResult, type RSToolErrorDescription } from '../models';
 
+/** Minimal domain error shape before mapping to {@link RSToolErrorDescription}. */
 export interface DomainErrorLike {
   code: number;
   from: number;
@@ -9,6 +10,7 @@ export interface DomainErrorLike {
   params?: readonly string[];
 }
 
+/** Minimal domain analysis shape before mapping to {@link AnalysisResult}. */
 export interface DomainAnalysisLike {
   success: boolean;
   type: Record<string, unknown> | null;
@@ -16,6 +18,7 @@ export interface DomainAnalysisLike {
   errors: DomainErrorLike[];
 }
 
+/** Map a domain parser/semantic error to the public diagnostic shape. */
 export function toPublicError(error: DomainErrorLike): RSToolErrorDescription {
   return {
     code: error.code,
@@ -25,6 +28,7 @@ export function toPublicError(error: DomainErrorLike): RSToolErrorDescription {
   };
 }
 
+/** Map a domain analysis result to the public {@link AnalysisResult} shape. */
 export function toPublicAnalysis(analysis: DomainAnalysisLike): AnalysisResult {
   return {
     success: analysis.success,

package/src/models/agent-workflow.ts

@@ -0,0 +1,66 @@
+import { type CstType } from './common';
+import { type ApplyConstituentsMode, type ApplyConstituentsResult, type ConstituentaDraft } from './constituenta';
+import { type DiagnosticRecord } from './diagnostic';
+import { type SessionHandle, type SessionRevision, type SessionState } from './session';
+
+/** Level of detail returned by {@link RSToolAgent.getSessionState}. */
+export type SessionStateDetail = 'summary' | 'full';
+
+/** Result of `getSessionState`: compact summary or full cloned session state. */
+export type SessionStateResult = SessionSummary | SessionState;
+
+/**
+ * Partial constituent update used in {@link ApplySchemaPatchInput}.
+ *
+ * `alias` is required; other fields are merged with any existing constituent
+ * or inferred from the alias prefix when omitted.
+ */
+export interface AgentConstituentaPatch extends Omit<Partial<ConstituentaDraft>, 'alias'> {
+  alias: string;
+}
+
+/** Input for {@link RSToolAgent.applySchemaPatch}. */
+export interface ApplySchemaPatchInput {
+  /** Metadata used only when a new session is created for this patch. */
+  initial?: {
+    alias?: string;
+    title?: string;
+    comment?: string;
+  };
+  /** Constituent patches to apply in dependency order. */
+  items: AgentConstituentaPatch[];
+  /** atomic: rollback on first failure; best_effort applies valid drafts. Default: atomic. */
+  mode?: ApplyConstituentsMode;
+  /** When set, a revision is recorded after a successful patch. */
+  commitMessage?: string;
+}
+
+/** Compact view of one constituent in a session summary. */
+export interface SessionSummaryItem {
+  id: number;
+  alias: string;
+  cstType: CstType;
+  analysisSuccess: boolean;
+}
+
+/** Compact session overview returned by default from `getSessionState`. */
+export interface SessionSummary {
+  sessionId: string;
+  contractVersion: string;
+  alias: string;
+  title: string;
+  comment: string;
+  itemCount: number;
+  modelItemCount: number;
+  diagnosticsCount: number;
+  items: SessionSummaryItem[];
+  diagnostics: DiagnosticRecord[];
+  lastRevision?: SessionRevision;
+}
+
+/** Result of {@link RSToolAgent.applySchemaPatch}. */
+export interface ApplySchemaPatchResult extends ApplyConstituentsResult {
+  session: SessionHandle;
+  summary: SessionSummary;
+  revision?: SessionRevision;
+}

package/src/models/analysis.ts

@@ -1,12 +1,19 @@
 import { type CstType, type RSToolErrorDescription, type ValueClass } from './common';
 
+/** Input for {@link RSToolAgent.analyzeExpression}. */
 export interface AnalyzeExpressionInput {
+  /** RSLang expression to parse and type-check. */
   expression: string;
+  /** Expected constituent type context for the expression. */
   cstType: CstType;
+  /** When true, append diagnostics to the session log. Default: false. */
+  recordDiagnostics?: boolean;
 }
 
+/** Outcome of parsing and semantic analysis for one expression. */
 export interface AnalysisResult {
   success: boolean;
+  /** Inferred RS type AST as a plain object, or `null` on failure. */
   type: Record<string, unknown> | null;
   valueClass: ValueClass | null;
   diagnostics: RSToolErrorDescription[];

package/src/models/common.ts

@@ -3,15 +3,22 @@ import { EvalStatus, type BasicBinding } from '@rsconcept/domain/library/rsmodel
 import { ValueClass } from '@rsconcept/domain/rslang';
 import { RSErrorCode } from '@rsconcept/domain/rslang/error';
 
+/** Constituent type enum (X, D, C, …). Re-exported from `@rsconcept/domain`. */
 export { CstType, EvalStatus, RSErrorCode, ValueClass };
+/** Named binding used in model evaluation. Re-exported from `@rsconcept/domain`. */
 export type { BasicBinding };
 
 /** Runtime evaluation value: number, nested array (set/tuple), or boolean 0/1. */
 export type RSToolValue = number | RSToolValue[];
 
+/** Language or validation error with source span and optional format parameters. */
 export interface RSToolErrorDescription {
+  /** Numeric error code (see {@link RSErrorCode}). */
   code: number;
+  /** Start offset in the analyzed expression. */
   from: number;
+  /** End offset in the analyzed expression. */
   to: number;
+  /** Interpolation values for localized error messages. */
   params?: readonly string[];
 }

package/src/models/constituenta.ts

@@ -2,22 +2,24 @@ import { type AnalysisResult } from './analysis';
 import { type CstType } from './common';
 import { type DiagnosticRecord } from './diagnostic';
 
+/** Constituent payload before analysis and merge into session state. */
 export interface ConstituentaDraft {
   id: number;
-  /** Alias */
+  /** Unique alias (e.g. `X1`, `D2`). */
   alias: string;
-  /** CST type */
+  /** Constituent type. */
   cstType: CstType;
-  /** Formal definition */
+  /** Formal RSLang definition. */
   definitionFormal: string;
-  /** Natural-language term */
+  /** Natural-language term. */
   term?: string;
-  /** Natural-language definition */
+  /** Natural-language definition. */
   definitionText?: string;
-  /** Convention or comment */
+  /** Convention or comment. */
   convention?: string;
 }
 
+/** Constituent stored in session state after analysis. */
 export interface ConstituentaState extends Omit<ConstituentaDraft, 'term' | 'definitionText' | 'convention'> {
   term: string;
   definitionText: string;
@@ -33,3 +35,19 @@ export interface AddOrUpdateConstituentaResult {
   state: ConstituentaState;
   diagnostics: DiagnosticRecord[];
 }
+
+/** How a multi-draft apply handles partial failures. */
+export type ApplyConstituentsMode = 'atomic' | 'best_effort';
+
+export interface ApplyConstituentsInput {
+  drafts: ConstituentaDraft[];
+  /** atomic: rollback on first failure; best_effort: apply valid drafts. Default: atomic. */
+  mode?: ApplyConstituentsMode;
+}
+
+export interface ApplyConstituentsResult {
+  success: boolean;
+  applied: ConstituentaState[];
+  failed: Array<{ draft: ConstituentaDraft; diagnostics: DiagnosticRecord[] }>;
+  diagnostics: DiagnosticRecord[];
+}

package/src/models/diagnostic.ts

@@ -1,12 +1,16 @@
 import { type RSToolErrorDescription } from './common';
 
+/** Persisted diagnostic for a failed or warned expression in a session. */
 export interface DiagnosticRecord {
   sessionId: string;
+  /** Constituent id when the diagnostic is tied to a stored item; omitted for scratch analysis. */
   constituentId?: number;
+  /** Expression text that was analyzed. */
   expression: string;
   error: RSToolErrorDescription;
 }
 
+/** Filters for {@link RSToolAgent.listDiagnostics}. */
 export interface ListDiagnosticsFilters {
   constituentId?: number;
 }

package/src/models/evaluation.ts

@@ -15,6 +15,17 @@ export interface EvaluateConstituentaInput {
   constituentId: number;
 }
 
+/** Evaluate a scratch expression or a stored constituent (provide one variant). */
+export interface EvaluateInput {
+  /** Scratch expression; requires `cstType`. */
+  expression?: string;
+  /** Type context when evaluating `expression`. */
+  cstType?: CstType;
+  /** Stored constituent id to evaluate. */
+  constituentId?: number;
+}
+
+/** Outcome of model evaluation for one expression or constituent. */
 export interface EvaluationResult {
   success: boolean;
   value: RSToolValue | BasicBinding | null;

package/src/models/import-detect.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType } from './common';
+import { detectImportKind, parseImportPayload } from './import-detect';
+
+describe('parseImportPayload', () => {
+  it('parses JSON strings', () => {
+    expect(parseImportPayload('{"title":"x"}')).toEqual({ title: 'x' });
+  });
+
+  it('returns objects unchanged', () => {
+    const payload = { title: 'x' };
+    expect(parseImportPayload(payload)).toBe(payload);
+  });
+});
+
+describe('detectImportKind', () => {
+  it('detects session exports', () => {
+    expect(detectImportKind({ contractVersion: '2.0.0', state: { items: [] } })).toBe('session');
+  });
+
+  it('detects portal schema JSON', () => {
+    expect(
+      detectImportKind({
+        contract_version: '1.0.0',
+        items: [{ id: 1, alias: 'X1', cst_type: CstType.BASE }]
+      })
+    ).toBe('portal-schema');
+  });
+
+  it('detects portal details JSON', () => {
+    expect(
+      detectImportKind({
+        title: 'Schema',
+        items: [{ id: 1, alias: 'X1', cst_type: CstType.BASE }]
+      })
+    ).toBe('portal-details');
+  });
+
+  it('rejects model JSON as schema session', () => {
+    expect(() =>
+      detectImportKind({
+        contract_version: '1.0.0',
+        items: [{ id: 1, type: 'basic', value: { 0: 'a' } }]
+      })
+    ).toThrow(/Portal model JSON cannot be imported/);
+  });
+
+  it('treats empty contract_version items as undetectable', () => {
+    expect(() =>
+      detectImportKind({
+        contract_version: '1.0.0',
+        items: []
+      })
+    ).toThrow(/Cannot detect import kind/);
+  });
+
+  it('rejects non-objects', () => {
+    expect(() => detectImportKind(null)).toThrow(/Invalid import payload/);
+    expect(() => detectImportKind('string')).toThrow(/Invalid import payload/);
+  });
+
+  it('rejects undetectable payloads', () => {
+    expect(() => detectImportKind({ title: 'orphan' })).toThrow(/Cannot detect import kind/);
+  });
+});

package/src/models/import-detect.ts

@@ -0,0 +1,42 @@
+import { type ImportDataKind } from './import-export';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function parseImportPayload(payload: string | object): unknown {
+  if (typeof payload === 'string') {
+    return JSON.parse(payload) as unknown;
+  }
+  return payload;
+}
+
+export function detectImportKind(data: unknown): Exclude<ImportDataKind, 'auto'> {
+  if (!isRecord(data)) {
+    throw new Error('Invalid import payload');
+  }
+
+  if ('contractVersion' in data && 'state' in data) {
+    return 'session';
+  }
+
+  if ('contract_version' in data && Array.isArray(data.items)) {
+    const items = data.items as unknown[];
+    if (items.length > 0) {
+      const first = items[0];
+      if (isRecord(first) && 'cst_type' in first) {
+        return 'portal-schema';
+      }
+      throw new Error('Portal model JSON cannot be imported as a schema session');
+    }
+  }
+
+  if (Array.isArray(data.items) && data.items.length > 0) {
+    const first = data.items[0];
+    if (isRecord(first) && 'cst_type' in first) {
+      return 'portal-details';
+    }
+  }
+
+  throw new Error('Cannot detect import kind; pass kind explicitly');
+}

package/src/models/import-export.ts

@@ -0,0 +1,24 @@
+import { type PortalModelImportData, type PortalSchemaImportData } from './portal-json';
+
+/** Portal export target: conceptual schema or model values. */
+export type PortalExportKind = 'schema' | 'model';
+
+/** Serialized JSON string or parsed object for export helpers. */
+export type ExportFormat = 'json' | 'object';
+
+/** Input for {@link RSToolAgent.exportPortal}. */
+export interface ExportPortalInput {
+  kind: PortalExportKind;
+  /** Default: `json` (string). Use `object` for structured data. */
+  format?: ExportFormat;
+}
+
+/**
+ * Import payload discriminator.
+ *
+ * Use `'auto'` to detect from JSON shape, or pass an explicit kind when ambiguous.
+ */
+export type ImportDataKind = 'auto' | 'session' | 'portal-schema' | 'portal-details';
+
+/** JSON string or Portal import object, depending on {@link ExportFormat}. */
+export type ExportPortalResult = string | PortalSchemaImportData | PortalModelImportData;

package/src/models/index.ts

@@ -1,3 +1,12 @@
+export {
+  type AgentConstituentaPatch,
+  type ApplySchemaPatchInput,
+  type ApplySchemaPatchResult,
+  type SessionStateDetail,
+  type SessionStateResult,
+  type SessionSummary,
+  type SessionSummaryItem
+} from './agent-workflow';
 export { type AnalysisResult, type AnalyzeExpressionInput } from './analysis';
 export {
   CstType,
@@ -8,34 +17,33 @@ export {
   type RSToolErrorDescription,
   type RSToolValue
 } from './common';
-export {
-  type AddOrUpdateConstituentaInput,
-  type AddOrUpdateConstituentaResult,
-  type ConstituentaDraft,
-  type ConstituentaState
-} from './constituenta';
+export { type ApplyConstituentsMode, type ConstituentaDraft, type ConstituentaState } from './constituenta';
 export { type DiagnosticRecord, type ListDiagnosticsFilters } from './diagnostic';
+export { type EvaluateInput, type EvaluationResult } from './evaluation';
 export {
-  type EvaluateConstituentaInput,
-  type EvaluateExpressionInput,
-  type EvaluationResult
-} from './evaluation';
+  type ExportFormat,
+  type ExportPortalInput,
+  type ExportPortalResult,
+  type ImportDataKind,
+  type PortalExportKind
+} from './import-export';
 export {
-  type ClearConstituentaValuesInput,
   type ModelValueState,
   type RecalculateModelResult,
   type SessionModelState,
   type SetConstituentaValueInput,
-  type SetConstituentaValuesInput
+  type SetModelValuesInput
 } from './model-value';
 export {
   PORTAL_JSON_CONTRACT_VERSION,
   type PortalImportMetadata,
   type PortalModelImportData,
+  type PortalRsformDetails,
   type PortalSchemaConstituenta,
   type PortalSchemaImportData,
-  type PortalTermForm
+  type PortalTermForm,
+  portalItemToDraft
 } from './portal-json';
 export { RSToolAgent } from './rstool-agent';
 export { type SessionHandle, type SessionRevision, type SessionState } from './session';
-export { CONTRACT_VERSION, type RSToolAgentContract } from './tool-contract';
+export { CONTRACT_VERSION, type RSToolAgentContract, type RSToolAgentOptions } from './tool-contract';

package/src/models/model-value.ts

@@ -1,5 +1,6 @@
 import { type BasicBinding, type EvalStatus, type RSToolValue } from './common';
 
+/** Model value for one constituent. */
 export interface ModelValueState {
   id: number;
   /** Frontend type string: `basic` or normalized effective typification. */
@@ -7,11 +8,14 @@ export interface ModelValueState {
   value: RSToolValue | BasicBinding;
 }
 
+/** All model values in a session. */
 export interface SessionModelState {
   items: ModelValueState[];
 }
 
+/** Set or replace the model value for one constituent. */
 export interface SetConstituentaValueInput {
+  /** Target constituent id. */
   target: number;
   /** Optional type override; inferred from schema when omitted. */
   type?: string;
@@ -26,6 +30,14 @@ export interface ClearConstituentaValuesInput {
   items: number[];
 }
 
+/** Input for {@link RSToolAgent.setModelValues}. */
+export interface SetModelValuesInput {
+  set?: SetConstituentaValueInput[];
+  /** Constituent ids whose model values should be cleared. */
+  clear?: number[];
+}
+
+/** Per-constituent outcome after {@link RSToolAgent.recalculateModel}. */
 export interface RecalculateModelResult {
   items: Array<{ id: number; alias: string; value: RSToolValue | null; status: EvalStatus }>;
 }

package/src/models/portal-json.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType } from './common';
+import { portalItemToDraft } from './portal-json';
+
+describe('portalItemToDraft', () => {
+  it('maps valid portal items', () => {
+    expect(
+      portalItemToDraft({
+        id: 1,
+        alias: 'D1',
+        cst_type: CstType.TERM,
+        definition_formal: '1+2',
+        term_raw: 'term',
+        definition_raw: 'def',
+        convention: 'conv'
+      })
+    ).toEqual({
+      id: 1,
+      alias: 'D1',
+      cstType: CstType.TERM,
+      definitionFormal: '1+2',
+      term: 'term',
+      definitionText: 'def',
+      convention: 'conv'
+    });
+  });
+
+  it('rejects unknown cst_type values', () => {
+    expect(() =>
+      portalItemToDraft({
+        id: 1,
+        alias: 'X1',
+        cst_type: 'not-a-cst-type'
+      })
+    ).toThrow(/Invalid cst_type "not-a-cst-type" for constituent "X1"/);
+  });
+});