@rsconcept/domain 2.2.0 → 2.3.0

package/src/library/rsform-api/attribution.ts

@@ -0,0 +1,87 @@
+/**
+ * Attribution remapping helpers for substitution and schema embedding.
+ */
+
+import { type Attribution } from '../rsform';
+
+function attributionKey(attr: Attribution): string {
+  return `${attr.container}:${attr.attribute}`;
+}
+
+/**
+ * Remap attributions when constituents are substituted (original → replacement).
+ * Drops self-loops and duplicates. Matches sandbox / backend substitute attribution rewrite.
+ */
+export function remapAttributionsUnderSubstitution(
+  attributions: readonly Attribution[],
+  origToSub: ReadonlyMap<number, number>
+): Attribution[] {
+  const result: Attribution[] = [];
+  const seen = new Set<string>();
+
+  for (const attr of attributions) {
+    if (!origToSub.has(attr.container) && !origToSub.has(attr.attribute)) {
+      const key = attributionKey(attr);
+      if (!seen.has(key)) {
+        seen.add(key);
+        result.push({ ...attr });
+      }
+      continue;
+    }
+
+    const container = origToSub.get(attr.container) ?? attr.container;
+    const attribute = origToSub.get(attr.attribute) ?? attr.attribute;
+    if (container === attribute) {
+      continue;
+    }
+    const key = `${container}:${attribute}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    result.push({ container, attribute });
+  }
+
+  return result;
+}
+
+/**
+ * Copy attributions whose both endpoints are in {@link sourceIdSet}, remapping ids via {@link idMap}.
+ * Appends onto a clone of {@link existing} with dedupe. Used by schema embedding / insert.
+ */
+export function importAttributions(
+  sourceAttributions: readonly Attribution[],
+  sourceIdSet: ReadonlySet<number>,
+  idMap: Readonly<Record<number, number>>,
+  existing: readonly Attribution[] = []
+): Attribution[] {
+  const result = existing.map(attr => ({ ...attr }));
+  const seen = new Set(result.map(attributionKey));
+
+  for (const attr of sourceAttributions) {
+    if (!sourceIdSet.has(attr.container) || !sourceIdSet.has(attr.attribute)) {
+      continue;
+    }
+    const container = idMap[attr.container];
+    const attribute = idMap[attr.attribute];
+    if (container === undefined || attribute === undefined || container === attribute) {
+      continue;
+    }
+    const key = `${container}:${attribute}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    result.push({ container, attribute });
+  }
+
+  return result;
+}
+
+/** Drop attributions that reference any id in {@link deletedIds}. */
+export function filterAttributions(
+  attributions: readonly Attribution[],
+  deletedIds: ReadonlySet<number>
+): Attribution[] {
+  return attributions.filter(attr => !deletedIds.has(attr.container) && !deletedIds.has(attr.attribute));
+}

package/src/library/rsform-api/index.ts

@@ -4,14 +4,19 @@
 
 export {
   addAliasReference,
+  allocateImportAliases,
   applyMappingToConstituents,
   argumentValuesToMapping,
+  buildSequentialAliasMapping,
+  type ConstituentaMappableFields,
   generateAlias,
+  maxAliasIndex,
   removeAliasReference,
   validateAliasFormat,
   validateNewAlias
 } from './alias';
 export { getAnalysisFor, refineAnalysisForDependencyCycles } from './analysis';
+export { filterAttributions, importAttributions, remapAttributionsUnderSubstitution } from './attribution';
 export {
   canHaveManualTypification,
   canProduceStructure,
@@ -26,7 +31,23 @@ export {
   typeClassForCstType
 } from './cst-type';
 export { applyFilterCategory, inferStatus, inferTemplate, inferTemplatedType, normalizeExpression } from './expression';
-export { restoreConstituentOrder } from './formal-graph';
+export { buildFormalDependencyGraph, restoreConstituentOrder } from './formal-graph';
 export { calculateSchemaStats, isSchemaIssue } from './stats';
 export { findCstByStructure, getStructureName, inferNewSpawnPosition } from './structure';
-export { sortItemsForInlineSynthesis } from './synthesis';
+export { applyConstituentSubstitutions, remapSubstitutionsAfterImport, type SubstitutionResult } from './substitution';
+export {
+  inlineSynthesis,
+  type InlineSynthesisInput,
+  type InlineSynthesisResult,
+  sortItemsForInlineSynthesis,
+  type SynthesizableConstituenta
+} from './synthesis';
+export {
+  buildDefinitionReferenceGraph,
+  buildTermReferenceGraph,
+  resolveAllConstituentTexts,
+  resolveConstituentTextChange,
+  type TextChangeOptions
+} from './text-resolution';
+export { insertItemAfter, moveIdsInOrder, reorderItemsByIds } from './transforms';
+export type { AliasTypedConstituenta, OrderableConstituenta, ResolvableConstituenta, SemanticRelations } from './types';

package/src/library/rsform-api/substitution.ts

@@ -0,0 +1,82 @@
+/**
+ * Constituenta substitution and post-import substitution remapping.
+ */
+
+import { type AliasMapping } from '../../rslang/api';
+import { type Attribution, type Substitution } from '../rsform';
+
+import { applyMappingToConstituents, type ConstituentaMappableFields } from './alias';
+import { remapAttributionsUnderSubstitution } from './attribution';
+
+/** Result of applying substitutions to a schema fragment. */
+export interface SubstitutionResult<T> {
+  items: T[];
+  attributions: Attribution[];
+  deletedIds: Set<number>;
+  /** Replacement constituent ids (survivors referenced by substitutions). */
+  replacementIds: number[];
+}
+
+/**
+ * Apply constituenta substitutions: remap attributions, drop originals, rewrite aliases in survivors.
+ * Does not resolve texts — call {@link resolveAllConstituentTexts} afterwards.
+ */
+export function applyConstituentSubstitutions<T extends ConstituentaMappableFields & { id: number; alias: string }>(
+  items: readonly T[],
+  attributions: readonly Attribution[],
+  substitutions: readonly Substitution[]
+): SubstitutionResult<T> {
+  if (substitutions.length === 0) {
+    return {
+      items: [...items],
+      attributions: attributions.map(attr => ({ ...attr })),
+      deletedIds: new Set(),
+      replacementIds: []
+    };
+  }
+
+  const byId = new Map(items.map(cst => [cst.id, cst]));
+  const mapping: AliasMapping = {};
+  const deletedIds = new Set<number>();
+  const origToSub = new Map<number, number>();
+  const replacementIds: number[] = [];
+
+  for (const { original, substitution } of substitutions) {
+    const originalCst = byId.get(original);
+    const substitutionCst = byId.get(substitution);
+    if (!originalCst || !substitutionCst) {
+      throw new Error(`applyConstituentSubstitutions: unknown constituenta ${original} -> ${substitution}`);
+    }
+    mapping[originalCst.alias] = substitutionCst.alias;
+    deletedIds.add(original);
+    origToSub.set(original, substitution);
+    replacementIds.push(substitution);
+  }
+
+  const nextItems = items.filter(cst => !deletedIds.has(cst.id));
+  applyMappingToConstituents(nextItems, mapping, false);
+
+  return {
+    items: nextItems,
+    attributions: remapAttributionsUnderSubstitution(attributions, origToSub),
+    deletedIds,
+    replacementIds
+  };
+}
+
+/**
+ * Remap substitution endpoints after source constituents were inserted under new ids.
+ * If {@link original} was imported, map it; otherwise map {@link substitution}.
+ */
+export function remapSubstitutionsAfterImport(
+  substitutions: readonly Substitution[],
+  sourceIdSet: ReadonlySet<number>,
+  idMap: Readonly<Record<number, number>>
+): Substitution[] {
+  return substitutions.map(sub => {
+    if (sourceIdSet.has(sub.original)) {
+      return { original: idMap[sub.original], substitution: sub.substitution };
+    }
+    return { original: sub.original, substitution: idMap[sub.substitution] };
+  });
+}

package/src/library/rsform-api/synthesis.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest';
+
+import { CstType } from '../rsform';
+
+import { inlineSynthesis } from './synthesis';
+
+function item(partial: {
+  id: number;
+  alias: string;
+  cst_type: CstType;
+  definition_formal?: string;
+  term_raw?: string;
+  definition_raw?: string;
+}) {
+  return {
+    id: partial.id,
+    alias: partial.alias,
+    cst_type: partial.cst_type,
+    definition_formal: partial.definition_formal ?? '',
+    typification_manual: '',
+    term_raw: partial.term_raw ?? '',
+    term_resolved: partial.term_raw ?? '',
+    term_forms: [] as { text: string; tags: string }[],
+    definition_raw: partial.definition_raw ?? '',
+    definition_resolved: partial.definition_raw ?? ''
+  };
+}
+
+describe('inlineSynthesis', () => {
+  it('keeps source aliases when receiver is empty', () => {
+    const result = inlineSynthesis({
+      receiverItems: [],
+      sourceItems: [item({ id: 10, alias: 'X9', cst_type: CstType.BASE, term_raw: 'person' })],
+      nextId: 1
+    });
+
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0].alias).toBe('X9');
+    expect(result.items[0].id).toBe(1);
+    expect(result.idMap).toEqual({ 10: 1 });
+    expect(result.nextId).toBe(2);
+    expect(result.aliasMapping).toEqual({});
+  });
+
+  it('allocates fresh aliases when receiver is non-empty', () => {
+    const result = inlineSynthesis({
+      receiverItems: [item({ id: 1, alias: 'X2', cst_type: CstType.BASE })],
+      sourceItems: [item({ id: 10, alias: 'X9', cst_type: CstType.BASE, term_raw: 'source' })],
+      nextId: 100
+    });
+
+    expect(result.items).toHaveLength(2);
+    expect(result.items[1].alias).toBe('X3');
+    expect(result.items[1].id).toBe(100);
+    expect(result.aliasMapping).toEqual({ X9: 'X3' });
+  });
+
+  it('applies substitutions after import (source original → receiver survivor)', () => {
+    const result = inlineSynthesis({
+      receiverItems: [item({ id: 1, alias: 'X1', cst_type: CstType.BASE, term_raw: 'keep' })],
+      sourceItems: [
+        item({
+          id: 20,
+          alias: 'X1',
+          cst_type: CstType.BASE,
+          term_raw: 'drop',
+          definition_formal: ''
+        })
+      ],
+      substitutions: [{ original: 20, substitution: 1 }],
+      nextId: 50
+    });
+
+    expect(result.items).toHaveLength(1);
+    expect(result.items[0].id).toBe(1);
+    expect(result.items[0].term_raw).toBe('keep');
+    expect(result.deletedIds).toEqual(new Set([50]));
+    expect(result.replacementIds).toEqual([1]);
+  });
+
+  it('remaps formal references when importing into non-empty receiver', () => {
+    const result = inlineSynthesis({
+      receiverItems: [item({ id: 1, alias: 'X1', cst_type: CstType.BASE })],
+      sourceItems: [
+        item({ id: 10, alias: 'X1', cst_type: CstType.BASE }),
+        item({
+          id: 11,
+          alias: 'S1',
+          cst_type: CstType.STRUCTURED,
+          definition_formal: 'ℬ(X1)'
+        })
+      ],
+      nextId: 2
+    });
+
+    const structured = result.items.find(cst => cst.cst_type === CstType.STRUCTURED)!;
+    expect(structured.alias).toBe('S1');
+    expect(structured.definition_formal).toBe('ℬ(X2)');
+  });
+
+  it('imports attributions with id remapping', () => {
+    const result = inlineSynthesis({
+      receiverItems: [item({ id: 1, alias: 'X1', cst_type: CstType.BASE })],
+      receiverAttributions: [],
+      sourceItems: [
+        item({ id: 10, alias: 'X1', cst_type: CstType.BASE }),
+        item({ id: 11, alias: 'S1', cst_type: CstType.STRUCTURED })
+      ],
+      sourceAttributions: [{ container: 10, attribute: 11 }],
+      nextId: 2
+    });
+
+    expect(result.attributions).toEqual([{ container: 2, attribute: 3 }]);
+  });
+
+  it('returns a clone when source is empty', () => {
+    const receiver = [item({ id: 1, alias: 'X1', cst_type: CstType.BASE })];
+    const result = inlineSynthesis({
+      receiverItems: receiver,
+      sourceItems: [],
+      nextId: 2
+    });
+    expect(result.items).toEqual(receiver);
+    expect(result.items).not.toBe(receiver);
+  });
+});

package/src/library/rsform-api/synthesis.ts

@@ -1,11 +1,150 @@
 /**
- * Inline synthesis helpers for library item selection.
+ * Schema embedding (synthesis): insert constituents from a source schema into a receiver,
+ * then apply an identification (substitution) table.
+ *
+ * Mirrors backend `inline_synthesis` / `insert_from` + `substitute`
+ * (Portal UI: «Встраивание схемы»).
  */
 
+import { type AliasMapping } from '../../rslang/api';
 import { type LibraryItem } from '../library';
-import { type RSForm } from '../rsform';
+import { type Attribution, type CstType, type RSForm, type Substitution } from '../rsform';
 
-/** Sorts library items relevant for InlineSynthesis with specified {@link RSForm}. */
+import { allocateImportAliases, applyMappingToConstituents, type ConstituentaMappableFields } from './alias';
+import { importAttributions } from './attribution';
+import { applyConstituentSubstitutions, remapSubstitutionsAfterImport } from './substitution';
+import { resolveAllConstituentTexts } from './text-resolution';
+import { type AliasTypedConstituenta, type ResolvableConstituenta } from './types';
+
+/** Constituent shape required for embedding / synthesis transforms. */
+export type SynthesizableConstituenta = ConstituentaMappableFields &
+  ResolvableConstituenta &
+  AliasTypedConstituenta & {
+    id: number;
+    alias: string;
+    cst_type: CstType;
+  };
+
+/** Input for {@link inlineSynthesis}. */
+export interface InlineSynthesisInput<T extends SynthesizableConstituenta> {
+  /** Receiver schema constituents (order preserved; imports append). */
+  receiverItems: readonly T[];
+  /** Receiver attributions (default empty). */
+  receiverAttributions?: readonly Attribution[];
+  /**
+   * Source constituents to insert (already filtered to the desired subset).
+   * Cloned; originals are not mutated.
+   */
+  sourceItems: readonly T[];
+  /** Source attributions whose both endpoints are among {@link sourceItems}. */
+  sourceAttributions?: readonly Attribution[];
+  /**
+   * Identification table using pre-import ids:
+   * one endpoint is a source id, the other a receiver id
+   * (same rules as backend embedding / InlineSynthesis).
+   */
+  substitutions?: readonly Substitution[];
+  /** Next free numeric id for inserted constituents. */
+  nextId: number;
+}
+
+/** Result of {@link inlineSynthesis}. */
+export interface InlineSynthesisResult<T extends SynthesizableConstituenta> {
+  items: T[];
+  attributions: Attribution[];
+  /** Updated next-id after inserts. */
+  nextId: number;
+  /** Source id → inserted id. */
+  idMap: Record<number, number>;
+  /** Alias remapping applied to imported constituents (empty when receiver was empty). */
+  aliasMapping: AliasMapping;
+  /** Ids removed by substitutions. */
+  deletedIds: Set<number>;
+  /** Ids of newly inserted constituents (before any were deleted by substitutions). */
+  insertedIds: number[];
+  /** Survivor ids referenced by applied substitutions. */
+  replacementIds: number[];
+}
+
+/**
+ * Embed {@link InlineSynthesisInput.sourceItems} into the receiver and apply substitutions.
+ * Resolves term/definition entity references on the result.
+ * Does not mutate inputs.
+ */
+export function inlineSynthesis<T extends SynthesizableConstituenta>(
+  input: InlineSynthesisInput<T>
+): InlineSynthesisResult<T> {
+  const sourceItems = input.sourceItems;
+  if (sourceItems.length === 0) {
+    return {
+      items: input.receiverItems.map(item => structuredClone(item)),
+      attributions: (input.receiverAttributions ?? []).map(attr => ({ ...attr })),
+      nextId: input.nextId,
+      idMap: {},
+      aliasMapping: {},
+      deletedIds: new Set(),
+      insertedIds: [],
+      replacementIds: []
+    };
+  }
+
+  const receiverItems = input.receiverItems.map(item => structuredClone(item));
+  let attributions = (input.receiverAttributions ?? []).map(attr => ({ ...attr }));
+  const aliasMapping = allocateImportAliases(receiverItems, sourceItems);
+  const idMap: Record<number, number> = {};
+  const inserted: T[] = [];
+  const sourceIdSet = new Set(sourceItems.map(cst => cst.id));
+  let nextId = input.nextId;
+
+  for (const cst of sourceItems) {
+    const newId = nextId;
+    nextId += 1;
+    idMap[cst.id] = newId;
+
+    const cloned = structuredClone(cst);
+    cloned.id = newId;
+    if (Object.keys(aliasMapping).length > 0) {
+      cloned.alias = aliasMapping[cst.alias];
+      applyMappingToConstituents([cloned], aliasMapping, false);
+    }
+    inserted.push(cloned);
+  }
+
+  attributions = importAttributions(input.sourceAttributions ?? [], sourceIdSet, idMap, attributions);
+  const items = receiverItems.concat(inserted);
+  resolveAllConstituentTexts(items);
+
+  const substitutions = input.substitutions ?? [];
+  if (substitutions.length === 0) {
+    return {
+      items,
+      attributions,
+      nextId,
+      idMap,
+      aliasMapping,
+      deletedIds: new Set(),
+      insertedIds: inserted.map(cst => cst.id),
+      replacementIds: []
+    };
+  }
+
+  const remapped = remapSubstitutionsAfterImport(substitutions, sourceIdSet, idMap);
+  const substituted = applyConstituentSubstitutions(items, attributions, remapped);
+  resolveAllConstituentTexts(substituted.items);
+
+  return {
+    items: substituted.items,
+    attributions: substituted.attributions,
+    nextId,
+    idMap,
+    aliasMapping,
+    deletedIds: substituted.deletedIds,
+    insertedIds: inserted.map(cst => cst.id),
+    replacementIds: substituted.replacementIds
+  };
+}
+
+/** Sorts library items relevant for schema embedding with specified {@link RSForm}. */
 export function sortItemsForInlineSynthesis(receiver: RSForm, items: readonly LibraryItem[]): LibraryItem[] {
   const result = items.filter(item => item.location === receiver.location);
   for (const item of items) {

package/src/library/rsform-api/text-resolution.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveConstituentTextChange } from './text-resolution';
+import { type ResolvableConstituenta } from './types';
+
+function row(
+  data: Partial<ResolvableConstituenta> & Pick<ResolvableConstituenta, 'alias' | 'id'>
+): ResolvableConstituenta {
+  return {
+    id: data.id,
+    alias: data.alias,
+    definition_raw: data.definition_raw ?? '',
+    definition_resolved: data.definition_resolved ?? '',
+    term_raw: data.term_raw ?? data.alias,
+    term_resolved: data.term_resolved ?? data.term_raw ?? data.alias,
+    term_forms: data.term_forms ?? []
+  };
+}
+
+describe('resolveConstituentTextChange', () => {
+  it('cascades term changes into dependent terms and definitions', () => {
+    const items = [
+      row({ id: 1, alias: 'T1', term_raw: 'base concept', term_resolved: 'base concept' }),
+      row({
+        id: 2,
+        alias: 'T2',
+        term_raw: '@{T1|nomn,sing}',
+        term_resolved: 'base concept',
+        definition_raw: '@{T1|nomn,sing}',
+        definition_resolved: 'base concept',
+        term_forms: [{ text: 'stale manual form', tags: 'gent,sing' }]
+      }),
+      row({ id: 3, alias: 'T3', definition_raw: '@{T2|nomn,sing}', definition_resolved: 'base concept' })
+    ];
+
+    items[0].term_raw = 'updated concept';
+    resolveConstituentTextChange(items, 1, {
+      termChanged: true,
+      termRawChanged: true,
+      definitionRawChanged: false,
+      clearTargetForms: true
+    });
+
+    expect(items[0].term_resolved).toBe('updated concept');
+    expect(items[1].term_resolved).toBe('updated concept');
+    expect(items[1].term_forms).toStrictEqual([]);
+    expect(items[1].definition_resolved).toBe('updated concept');
+    expect(items[2].definition_resolved).toBe('updated concept');
+  });
+
+  it('uses updated manual forms as a term change trigger', () => {
+    const items = [
+      row({ id: 1, alias: 'T1', term_raw: 'base concept', term_resolved: 'base concept' }),
+      row({ id: 2, alias: 'T2', term_raw: '@{T1|gent,sing}', term_resolved: 'base concept' })
+    ];
+
+    items[0].term_forms = [{ text: 'manual genitive singular', tags: 'gent,sing' }];
+    resolveConstituentTextChange(items, 1, {
+      termChanged: true,
+      termRawChanged: false,
+      definitionRawChanged: false,
+      clearTargetForms: false
+    });
+
+    expect(items[1].term_resolved).toBe('manual genitive singular');
+  });
+
+  it('does not cascade definition-only edits', () => {
+    const items = [
+      row({ id: 1, alias: 'T1', term_raw: 'base concept', term_resolved: 'base concept' }),
+      row({ id: 2, alias: 'T2', definition_raw: '@{T1|nomn,sing}', definition_resolved: 'base concept' }),
+      row({ id: 3, alias: 'T3', definition_raw: '@{T2|nomn,sing}', definition_resolved: 'old T2' })
+    ];
+
+    items[1].definition_raw = 'Only @{T1|nomn,sing}';
+    resolveConstituentTextChange(items, 2, {
+      termChanged: false,
+      termRawChanged: false,
+      definitionRawChanged: true,
+      clearTargetForms: false
+    });
+
+    expect(items[1].definition_resolved).toBe('Only base concept');
+    expect(items[2].definition_resolved).toBe('old T2');
+  });
+});