@rsconcept/domain 1.0.0

package/src/cctext/language-api.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest';
+
+import { Grammeme } from './language';
+import {
+  extractEntities,
+  generateNominalLexeme,
+  parseEntityReference,
+  parseGrammemes,
+  parseReference,
+  parseSyntacticReference,
+  resolveTextReferences,
+  wordFormEquals
+} from './language-api';
+
+describe('Testing wordform equality', () => {
+  it('empty input', () => {
+    expect(wordFormEquals({ text: '', grams: [] }, { text: '', grams: [] })).toEqual(true);
+    expect(wordFormEquals({ text: '', grams: [] }, { text: '11', grams: [] })).toEqual(true);
+    expect(wordFormEquals({ text: '11', grams: [] }, { text: '', grams: [] })).toEqual(true);
+    expect(wordFormEquals({ text: '11', grams: [] }, { text: '42', grams: [] })).toEqual(true);
+    expect(wordFormEquals({ text: '', grams: ['nomn'] }, { text: '', grams: [] })).toEqual(false);
+    expect(wordFormEquals({ text: '11', grams: ['nomn'] }, { text: '11', grams: [] })).toEqual(false);
+    expect(wordFormEquals({ text: '', grams: [] }, { text: '', grams: ['nomn'] })).toEqual(false);
+    expect(wordFormEquals({ text: '11', grams: [] }, { text: '11', grams: ['nomn'] })).toEqual(false);
+  });
+
+  it('regular grammemes', () => {
+    expect(wordFormEquals({ text: '', grams: ['nomn'] }, { text: '', grams: ['nomn'] })).toEqual(true);
+    expect(wordFormEquals({ text: '', grams: ['nomn'] }, { text: '', grams: ['sing'] })).toEqual(false);
+    expect(wordFormEquals({ text: '', grams: ['nomn', 'sing'] }, { text: '', grams: ['nomn', 'sing'] })).toEqual(true);
+    expect(wordFormEquals({ text: '', grams: ['nomn', 'sing'] }, { text: '11', grams: ['nomn', 'sing'] })).toEqual(
+      true
+    );
+    expect(wordFormEquals({ text: '11', grams: ['nomn', 'sing'] }, { text: '', grams: ['nomn', 'sing'] })).toEqual(
+      true
+    );
+    expect(wordFormEquals({ text: '11', grams: ['nomn', 'sing'] }, { text: '11', grams: ['nomn', 'sing'] })).toEqual(
+      true
+    );
+    expect(wordFormEquals({ text: '42', grams: ['nomn', 'sing'] }, { text: '11', grams: ['nomn', 'sing'] })).toEqual(
+      true
+    );
+    expect(wordFormEquals({ text: '', grams: ['nomn', 'sing'] }, { text: '', grams: ['sing', 'nomn'] })).toEqual(false);
+    expect(wordFormEquals({ text: '', grams: ['nomn', 'sing'] }, { text: '', grams: ['nomn'] })).toEqual(false);
+    expect(wordFormEquals({ text: '', grams: ['nomn', 'nomn'] }, { text: '', grams: ['nomn'] })).toEqual(false);
+  });
+});
+
+describe('Testing grammeme parsing', () => {
+  it('empty input', () => {
+    expect(parseGrammemes('')).toStrictEqual([]);
+    expect(parseGrammemes(' ')).toStrictEqual([]);
+    expect(parseGrammemes(' , ')).toStrictEqual([]);
+  });
+
+  it('regular grammemes', () => {
+    expect(parseGrammemes('sing,nomn')).toStrictEqual([Grammeme.sing, Grammeme.nomn]);
+    expect(parseGrammemes('nomn,sing')).toStrictEqual([Grammeme.sing, Grammeme.nomn]);
+  });
+
+  it('custom grammemes', () => {
+    expect(parseGrammemes('nomn,invalid,sing')).toStrictEqual([Grammeme.sing, Grammeme.nomn, 'invalid']);
+    expect(parseGrammemes('invalid,test')).toStrictEqual(['invalid', 'test']);
+  });
+});
+
+describe('Testing nominal lexeme generation', () => {
+  it('generates every supported noun form with nominal text', () => {
+    const response = generateNominalLexeme({ text: 'nominal concept' });
+
+    expect(response.items).toStrictEqual([
+      { text: 'nominal concept', grams: 'sing,nomn' },
+      { text: 'nominal concept', grams: 'sing,gent' },
+      { text: 'nominal concept', grams: 'sing,datv' },
+      { text: 'nominal concept', grams: 'sing,accs' },
+      { text: 'nominal concept', grams: 'sing,ablt' },
+      { text: 'nominal concept', grams: 'sing,loct' },
+      { text: 'nominal concept', grams: 'plur,nomn' },
+      { text: 'nominal concept', grams: 'plur,gent' },
+      { text: 'nominal concept', grams: 'plur,datv' },
+      { text: 'nominal concept', grams: 'plur,accs' },
+      { text: 'nominal concept', grams: 'plur,ablt' },
+      { text: 'nominal concept', grams: 'plur,loct' }
+    ]);
+  });
+});
+
+describe('Testing reference parsing', () => {
+  it('entity reference', () => {
+    expect(parseEntityReference('@{ X1 | nomn,sing }')).toStrictEqual({ entity: 'X1', tags: ['sing', 'nomn'] });
+    expect(parseEntityReference('@{X1|nomn,sing}')).toStrictEqual({ entity: 'X1', tags: ['sing', 'nomn'] });
+    expect(parseEntityReference('@{X111|nomn,sing}')).toStrictEqual({ entity: 'X111', tags: ['sing', 'nomn'] });
+  });
+
+  it('syntactic reference', () => {
+    expect(parseSyntacticReference('@{1|test test}')).toStrictEqual({ offset: 1, nominal: 'test test' });
+    expect(parseSyntacticReference('@{101|test test}')).toStrictEqual({ offset: 101, nominal: 'test test' });
+    expect(parseSyntacticReference('@{-1|test test}')).toStrictEqual({ offset: -1, nominal: 'test test' });
+    expect(parseSyntacticReference('@{-99|test test}')).toStrictEqual({ offset: -99, nominal: 'test test' });
+  });
+
+  it('validated reference', () => {
+    expect(parseReference('@{X1|nomn, sing}')).toStrictEqual({
+      type: 'entity',
+      data: { entity: 'X1', tags: ['sing', 'nomn'] }
+    });
+    expect(parseReference('@{-1|derived term}')).toStrictEqual({
+      type: 'syntax',
+      data: { offset: -1, nominal: 'derived term' }
+    });
+    expect(parseReference('@{0|derived term}')).toBeNull();
+    expect(parseReference('@{-0|derived term}')).toBeNull();
+    expect(parseReference('@{1|}')).toBeNull();
+  });
+});
+
+describe('Testing reference resolution', () => {
+  it('extracts entity references', () => {
+    expect(extractEntities('@{X1|} and @{1|nominal} and @{X2|sing,gent} and @{X1|plur,nomn}')).toStrictEqual([
+      'X1',
+      'X2'
+    ]);
+  });
+
+  it('resolves entity references using nominal and manual forms', () => {
+    const context = {
+      X1: {
+        nominal: 'base term',
+        forms: [{ text: 'manual plural', grams: [Grammeme.plur, Grammeme.nomn] }]
+      }
+    };
+
+    expect(resolveTextReferences('Use @{X1|nomn,sing}.', context)).toBe('Use base term.');
+    expect(resolveTextReferences('Use @{X1|plur,nomn}.', context)).toBe('Use manual plural.');
+    expect(resolveTextReferences('Use @{X1|sing,gent}.', context)).toBe('Use base term.');
+  });
+
+  it('resolves syntactic references to nominal text without inflection', () => {
+    const context = {
+      X1: {
+        nominal: 'base term'
+      }
+    };
+
+    expect(resolveTextReferences('@{X1|nomn,sing} @{-1|derived term}', context)).toBe('base term derived term');
+    expect(resolveTextReferences('@{1|derived term} @{X1|nomn,sing}', context)).toBe('derived term base term');
+    expect(resolveTextReferences('@{-1|derived term}', context)).toBe('!Некорректное смещение: -1!');
+  });
+});

package/src/cctext/language-api.ts

@@ -0,0 +1,285 @@
+/**
+ * Module: Natural language model API.
+ */
+
+import {
+  Case,
+  type EntityReference,
+  Grammeme,
+  type IReference,
+  Plurality,
+  ReferenceType,
+  type SyntacticReference,
+  type TermContext,
+  type TermContextItem,
+  type WordForm
+} from './language';
+
+interface Position {
+  from: number;
+  to: number;
+}
+
+interface ResolvedReference {
+  ref: IReference;
+  resolved: string;
+  posInput: Position;
+}
+
+const REFERENCE_PATTERN = /@{[^{}]*?}/g;
+const ENTITY_REFERENCE_PATTERN = /@{([^0-9\-][^}|{]*?)\|([^}|{]*?)}/g;
+
+/** Represents generated lexeme forms. */
+export interface Lexeme {
+  items: { text: string; grams: string }[];
+}
+
+/** Equality comparator for {@link WordForm}. Compares a set of Grammemes attached to wordforms. */
+export function wordFormEquals(left: WordForm, right: WordForm): boolean {
+  if (left.grams.length !== right.grams.length) {
+    return false;
+  }
+  for (let index = 0; index < left.grams.length; ++index) {
+    if (left.grams[index] !== right.grams[index]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Transforms {@link Grammeme} enumeration to {@link Grammeme}. */
+export function parseGrammemes(termForm: string): Grammeme[] {
+  const result: Grammeme[] = [];
+  for (const chunk of termForm.split(',')) {
+    const gram = chunk.trim();
+    if (gram !== '') {
+      result.push(gram as Grammeme);
+    }
+  }
+  return result.sort(grammemeCompare);
+}
+
+/** Generates all supported noun forms using nominal text for every form. */
+export function generateNominalLexeme(data: { text: string }): Lexeme {
+  return {
+    items: Plurality.flatMap(plurality =>
+      Case.map(gramCase => ({
+        text: data.text,
+        grams: `${plurality},${gramCase}`
+      }))
+    )
+  };
+}
+
+/**
+ * Extracts {@link EntityReference} from string representation.
+ *
+ * @param text - Reference text in a valid pattern. Must fit format '\@\{GLOBAL_ID|GRAMMEMES\}'
+ */
+export function parseEntityReference(text: string): EntityReference {
+  const ref = parseReference(text);
+  if (ref?.type !== ReferenceType.ENTITY) {
+    throw new Error(`Invalid entity reference: ${text}`);
+  }
+  return ref.data as EntityReference;
+}
+
+/**
+ * Extracts {@link SyntacticReference} from string representation.
+ *
+ * @param text - Reference text in a valid pattern. Must fit format '\@\{OFFSET|NOMINAL_FORM\}'
+ */
+export function parseSyntacticReference(text: string): SyntacticReference {
+  const ref = parseReference(text);
+  if (ref?.type !== ReferenceType.SYNTACTIC) {
+    throw new Error(`Invalid syntactic reference: ${text}`);
+  }
+  return ref.data as SyntacticReference;
+}
+
+/** Extracts a validated reference from string representation. */
+export function parseReference(text: string): IReference | null {
+  if (text.length < 4 || !text.startsWith('@{') || !text.endsWith('}')) {
+    return null;
+  }
+
+  const blocks = text
+    .slice(2, text.length - 1)
+    .split('|')
+    .map(block => block.trim());
+  if (blocks.length !== 2 || blocks[0] === '' || blocks[0].startsWith('0')) {
+    return null;
+  }
+
+  if (blocks[0].startsWith('-') || /^[1-9]/.test(blocks[0])) {
+    const offset = Number(blocks[0]);
+    if (!Number.isInteger(offset) || offset === 0 || blocks[1] === '') {
+      return null;
+    }
+    return {
+      type: ReferenceType.SYNTACTIC,
+      data: { offset, nominal: blocks[1] }
+    };
+  }
+
+  return {
+    type: ReferenceType.ENTITY,
+    data: { entity: blocks[0], tags: parseGrammemes(blocks[1].replaceAll(' ', '')) }
+  };
+}
+
+/** Extracts unique entity aliases referenced by text. */
+export function extractEntities(text: string): string[] {
+  const result: string[] = [];
+  for (const segment of text.matchAll(ENTITY_REFERENCE_PATTERN)) {
+    const entity = segment[1].trim();
+    if (!result.includes(entity)) {
+      result.push(entity);
+    }
+  }
+  return result;
+}
+
+/** Resolves text references using nominal terms and optional manually edited forms. */
+export function resolveTextReferences(text: string, context: TermContext): string {
+  const references = parseReferences(text);
+  if (references.length === 0) {
+    return text;
+  }
+
+  for (const ref of references) {
+    if (ref.ref.type === ReferenceType.ENTITY) {
+      ref.resolved = resolveEntity(ref.ref.data as EntityReference, context);
+    }
+  }
+  references.forEach((ref, index) => {
+    if (ref.ref.type === ReferenceType.SYNTACTIC) {
+      ref.resolved = resolveSyntactic(ref.ref.data as SyntacticReference, index, references);
+    }
+  });
+
+  let posInput = 0;
+  let output = '';
+  for (const ref of references) {
+    output += text.substring(posInput, ref.posInput.from);
+    output += ref.resolved;
+    posInput = ref.posInput.to;
+  }
+  output += text.substring(posInput);
+  return output;
+}
+
+/** Transforms {@link IReference} to string representation. */
+export function referenceToString(ref: IReference): string {
+  switch (ref.type) {
+    case ReferenceType.ENTITY: {
+      const entity = ref.data as EntityReference;
+      return `@{${entity.entity}|${entity.tags.join(',')}}`;
+    }
+    case ReferenceType.SYNTACTIC: {
+      const syntactic = ref.data as SyntacticReference;
+      return `@{${syntactic.offset}|${syntactic.nominal}}`;
+    }
+  }
+}
+
+// ===== Internals =======
+
+/** Compares {@link Grammeme} based on Grammeme enum and alpha order for strings. */
+function grammemeCompare(left: Grammeme, right: Grammeme): number {
+  const indexLeft = Object.values(Grammeme).findIndex(gram => gram === left);
+  const indexRight = Object.values(Grammeme).findIndex(gram => gram === right);
+  if (indexLeft === -1 && indexRight === -1) {
+    return left.localeCompare(right);
+  } else if (indexLeft === -1 && indexRight !== -1) {
+    return 1;
+  } else if (indexLeft !== -1 && indexRight === -1) {
+    return -1;
+  } else {
+    return indexLeft - indexRight;
+  }
+}
+
+function parseReferences(text: string): ResolvedReference[] {
+  const result: ResolvedReference[] = [];
+  for (const segment of text.matchAll(REFERENCE_PATTERN)) {
+    const ref = parseReference(segment[0]);
+    if (ref) {
+      result.push({
+        ref,
+        resolved: '',
+        posInput: { from: segment.index ?? 0, to: (segment.index ?? 0) + segment[0].length }
+      });
+    }
+  }
+  return result;
+}
+
+function resolveEntity(ref: EntityReference, context: TermContext): string {
+  const entity = context[ref.entity];
+  if (!entity) {
+    return `!Неизвестная сущность: ${ref.entity}!`;
+  }
+
+  const resolved = getEntityForm(entity, ref.tags);
+  return resolved === '' ? `!Отсутствует термин: ${ref.entity}!` : resolved;
+}
+
+function getEntityForm(entity: TermContextItem, grams: Grammeme[]): string {
+  if (grams.length === 0) {
+    return entity.nominal;
+  }
+
+  const manual = entity.forms?.find(form => matchGrams(grams, form.grams));
+  return manual?.text ?? entity.nominal;
+}
+
+function matchGrams(query: Grammeme[], candidate: Grammeme[]): boolean {
+  for (const gram of candidate) {
+    if (!query.includes(gram)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function resolveSyntactic(ref: SyntacticReference, index: number, references: ResolvedReference[]): string {
+  const master = findSyntacticMaster(ref.offset, index, references);
+  if (!master) {
+    return `!Некорректное смещение: ${ref.offset}!`;
+  }
+  return ref.nominal;
+}
+
+function findSyntacticMaster(
+  offset: number,
+  index: number,
+  references: ResolvedReference[]
+): ResolvedReference | undefined {
+  if (offset > 0) {
+    let position = index + 1;
+    let left = offset;
+    while (position < references.length) {
+      if (references[position].ref.type === ReferenceType.ENTITY) {
+        if (left === 1) {
+          return references[position];
+        }
+        left -= 1;
+      }
+      position += 1;
+    }
+  } else {
+    let position = index - 1;
+    let left = offset;
+    while (position >= 0) {
+      if (references[position].ref.type === ReferenceType.ENTITY) {
+        if (left === -1) {
+          return references[position];
+        }
+        left += 1;
+      }
+      position -= 1;
+    }
+  }
+  return undefined;
+}

package/src/cctext/language.ts

@@ -0,0 +1,80 @@
+/**
+ * Module: Natural language model declarations.
+ */
+
+/** Represents single unit of language Morphology. */
+// prettier-ignore
+export const Grammeme = {
+  // Число
+  sing: 'sing', plur: 'plur',
+
+  // Падеж
+  nomn: 'nomn', gent: 'gent', datv: 'datv',
+  accs: 'accs', ablt: 'ablt', loct: 'loct',
+} as const;
+export type Grammeme = (typeof Grammeme)[keyof typeof Grammeme];
+
+/** Represents case language concept. */
+export const Case: Grammeme[] = [
+  Grammeme.nomn,
+  Grammeme.gent,
+  Grammeme.datv,
+  Grammeme.accs,
+  Grammeme.ablt,
+  Grammeme.loct
+] as const;
+
+/** Represents plurality language concept. */
+export const Plurality: Grammeme[] = [Grammeme.sing, Grammeme.plur] as const;
+
+/** Represents specific wordform attached to {@link Grammeme}s. */
+export interface WordForm {
+  text: string;
+  grams: Grammeme[];
+}
+
+/** Represents a term available for text reference resolution. */
+export interface TermContextItem {
+  nominal: string;
+  forms?: WordForm[];
+}
+
+/** Represents term lookup context keyed by entity alias. */
+export type TermContext = Record<string, TermContextItem>;
+
+/**
+ * Represents list of {@link Grammeme}s available in reference construction.
+ */
+// prettier-ignore
+export const supportedGrammemes = [
+  Grammeme.sing, Grammeme.plur,
+  Grammeme.nomn, Grammeme.gent, Grammeme.datv,
+  Grammeme.accs, Grammeme.ablt, Grammeme.loct,
+] as const;
+
+// ====== Reference resolution =====
+
+/** Represents text reference type. */
+export const ReferenceType = {
+  ENTITY: 'entity',
+  SYNTACTIC: 'syntax'
+} as const;
+export type ReferenceType = (typeof ReferenceType)[keyof typeof ReferenceType];
+
+/** Represents entity reference payload. */
+export interface EntityReference {
+  entity: string;
+  tags: Grammeme[];
+}
+
+/** Represents syntactic reference payload. */
+export interface SyntacticReference {
+  offset: number;
+  nominal: string;
+}
+
+/** Represents abstract reference data. */
+export interface IReference {
+  type: ReferenceType;
+  data: EntityReference | SyntacticReference;
+}