@rsconcept/domain 2.1.2 → 2.3.0

package/src/library/rsform-api/formal-graph.ts

@@ -0,0 +1,195 @@
+/**
+ * Formal dependency graph and declaration-order restore for RSForm constituents.
+ */
+
+import { Graph } from '../../graph';
+import { extractGlobals } from '../../rslang/api';
+import { CstType } from '../rsform';
+
+import { computeSemanticRelations } from './semantic-relations';
+import { type OrderableConstituenta, type SemanticRelations } from './types';
+
+/**
+ * Build the formal dependency graph: supplier → dependent.
+ * Matches backend {@code RSForm.graph_formal}.
+ */
+export function buildFormalDependencyGraph(items: readonly OrderableConstituenta[]): Graph<number> {
+  const graph = new Graph<number>();
+  const byAlias = new Map(items.map(cst => [cst.alias, cst]));
+  for (const cst of items) {
+    graph.addNode(cst.id);
+  }
+  for (const cst of items) {
+    for (const alias of extractGlobals(cst.definition_formal)) {
+      const supplier = byAlias.get(alias);
+      if (supplier) {
+        graph.addEdge(supplier.id, cst.id);
+      }
+    }
+  }
+  return graph;
+}
+
+/**
+ * Reorder constituents: formal topology hard, semantic children sticky when ready,
+ * otherwise stable against type/kernel preferred ranks.
+ *
+ * One Kahn pass over the formal dependency graph.
+ */
+export function restoreConstituentOrder<T extends OrderableConstituenta>(
+  items: readonly T[],
+  graph: Graph<number> = buildFormalDependencyGraph(items),
+  relations: SemanticRelations = computeSemanticRelations(items, graph)
+): T[] {
+  if (items.length <= 1) {
+    return [...items];
+  }
+
+  const byId = new Map(items.map(cst => [cst.id, cst]));
+  const preferred = kernelPriority(items, graph, relations.parentOf);
+  const rank = new Map(preferred.map((cst, index) => [cst.id, index]));
+
+  const remainingInputs = new Map<number, number>();
+  for (const cst of preferred) {
+    const inputs = graph.at(cst.id)?.inputs ?? [];
+    remainingInputs.set(
+      cst.id,
+      inputs.reduce((count, src) => count + (rank.has(src) ? 1 : 0), 0)
+    );
+  }
+
+  const ready = new Set<number>();
+  for (const cst of preferred) {
+    if ((remainingInputs.get(cst.id) ?? 0) === 0) {
+      ready.add(cst.id);
+    }
+  }
+
+  const children = new Map<number, number[]>();
+  for (const cst of preferred) {
+    children.set(
+      cst.id,
+      (relations.childrenOf.get(cst.id) ?? []).filter(childId => rank.has(childId))
+    );
+  }
+
+  const result: T[] = [];
+  const pendingChildren: number[] = [];
+
+  function enqueueSticky(candidateIds: readonly number[]): void {
+    const sticky = candidateIds.filter(
+      childId => ready.has(childId) && !pendingChildren.includes(childId)
+    );
+    sticky.sort((left, right) => (rank.get(left) ?? 0) - (rank.get(right) ?? 0));
+    pendingChildren.push(...sticky);
+  }
+
+  function pickReady(): number {
+    while (pendingChildren.length > 0) {
+      const childId = pendingChildren.shift()!;
+      if (ready.has(childId)) {
+        return childId;
+      }
+    }
+    let best = -1;
+    let bestRank = Number.POSITIVE_INFINITY;
+    for (const nodeId of ready) {
+      const nodeRank = rank.get(nodeId) ?? Number.POSITIVE_INFINITY;
+      if (nodeRank < bestRank) {
+        best = nodeId;
+        bestRank = nodeRank;
+      }
+    }
+    return best;
+  }
+
+  while (ready.size > 0 || pendingChildren.length > 0) {
+    if (ready.size === 0) {
+      pendingChildren.length = 0;
+      continue;
+    }
+    const nodeId = pickReady();
+    ready.delete(nodeId);
+    result.push(byId.get(nodeId)!);
+
+    for (const dependentId of graph.at(nodeId)?.outputs ?? []) {
+      if (!remainingInputs.has(dependentId)) {
+        continue;
+      }
+      const next = (remainingInputs.get(dependentId) ?? 0) - 1;
+      remainingInputs.set(dependentId, next);
+      if (next === 0) {
+        ready.add(dependentId);
+      }
+    }
+
+    enqueueSticky(children.get(nodeId) ?? []);
+  }
+
+  if (result.length < preferred.length) {
+    const placed = new Set(result.map(cst => cst.id));
+    for (const cst of preferred) {
+      if (!placed.has(cst.id)) {
+        result.push(cst);
+      }
+    }
+  }
+
+  return result;
+}
+
+function kernelPriority<T extends OrderableConstituenta>(
+  items: readonly T[],
+  graph: Graph<number>,
+  parentOf: Map<number, number>
+): T[] {
+  const byId = new Map(items.map(cst => [cst.id, cst]));
+  const seen = new Set<number>();
+  const result: T[] = [];
+
+  function push(cst: T): void {
+    if (seen.has(cst.id)) {
+      return;
+    }
+    seen.add(cst.id);
+    result.push(cst);
+  }
+
+  for (const cst of items) {
+    if (cst.cst_type === CstType.BASE) {
+      push(cst);
+    }
+  }
+  for (const cst of items) {
+    if (cst.cst_type === CstType.CONSTANT) {
+      push(cst);
+    }
+  }
+  for (const cst of items) {
+    if ((graph.at(cst.id)?.inputs.length ?? 0) === 0) {
+      push(cst);
+    }
+  }
+
+  const kernelSeeds = items
+    .filter(cst => {
+      const parentId = parentOf.get(cst.id) ?? cst.id;
+      const parent = byId.get(parentId);
+      return (
+        cst.cst_type === CstType.STRUCTURED ||
+        cst.cst_type === CstType.AXIOM ||
+        parent?.cst_type === CstType.STRUCTURED
+      );
+    })
+    .map(cst => cst.id);
+  const kernel = new Set<number>([...kernelSeeds, ...graph.expandAllInputs(kernelSeeds)]);
+  for (const cst of items) {
+    if (kernel.has(cst.id)) {
+      push(cst);
+    }
+  }
+  for (const cst of items) {
+    push(cst);
+  }
+  return result;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Module: API for formal representation for systems of concepts.
+ */
+
+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,
+  getCstTypePrefix,
+  guessCstType,
+  inferClass,
+  isBaseSet,
+  isBasicConcept,
+  isFunctional,
+  isLogical,
+  isTemplateCst,
+  typeClassForCstType
+} from './cst-type';
+export { applyFilterCategory, inferStatus, inferTemplate, inferTemplatedType, normalizeExpression } from './expression';
+export { buildFormalDependencyGraph, restoreConstituentOrder } from './formal-graph';
+export { calculateSchemaStats, isSchemaIssue } from './stats';
+export { findCstByStructure, getStructureName, inferNewSpawnPosition } from './structure';
+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/semantic-relations.ts

@@ -0,0 +1,117 @@
+/**
+ * Semantic parent/children used when restoring constituent order.
+ */
+
+import { type Graph } from '../../graph';
+import { extractGlobals, isSimpleExpression, splitTemplateDefinition } from '../../rslang/api';
+import { CstType } from '../rsform';
+
+import { isBaseSet, isFunctional } from './cst-type';
+import { inferTemplate } from './expression';
+import { type OrderableConstituenta, type SemanticRelations } from './types';
+
+/**
+ * Infer semantic parent/children used for clustering during restore order.
+ * Port of backend {@code SemanticInfo}.
+ */
+export function computeSemanticRelations(
+  items: readonly OrderableConstituenta[],
+  graph: Graph<number>
+): SemanticRelations {
+  const byId = new Map(items.map(cst => [cst.id, cst]));
+  const byAlias = new Map(items.map(cst => [cst.alias, cst]));
+  const isTemplate = new Map<number, boolean>();
+  const isSimple = new Map<number, boolean>();
+  const parentOf = new Map<number, number>();
+  const childrenOf = new Map<number, number[]>();
+
+  for (const cst of items) {
+    parentOf.set(cst.id, cst.id);
+    childrenOf.set(cst.id, []);
+  }
+
+  function needCheckHead(sources: Set<number>, head: string): boolean {
+    if (sources.size === 0) {
+      return true;
+    }
+    if (sources.size !== 1) {
+      return false;
+    }
+    const base = byId.get([...sources][0])!;
+    return !isFunctional(base.cst_type) || splitTemplateDefinition(base.definition_formal).head !== head;
+  }
+
+  function extractSources(target: OrderableConstituenta): Set<number> {
+    const sources = new Set<number>();
+    if (!isFunctional(target.cst_type)) {
+      for (const parentId of graph.at(target.id)?.inputs ?? []) {
+        if (!(isTemplate.get(parentId) && isSimple.get(parentId))) {
+          sources.add(parentOf.get(parentId) ?? parentId);
+        }
+      }
+      return sources;
+    }
+
+    const expression = splitTemplateDefinition(target.definition_formal);
+    for (const alias of extractGlobals(expression.body)) {
+      const parent = byAlias.get(alias);
+      if (!parent) {
+        continue;
+      }
+      if (!(isTemplate.get(parent.id) && isSimple.get(parent.id))) {
+        sources.add(parentOf.get(parent.id) ?? parent.id);
+      }
+    }
+    if (needCheckHead(sources, expression.head)) {
+      for (const alias of extractGlobals(expression.head)) {
+        const parent = byAlias.get(alias);
+        if (!parent) {
+          continue;
+        }
+        if (!isBaseSet(parent.cst_type) && !(isTemplate.get(parent.id) && isSimple.get(parent.id))) {
+          sources.add(parentOf.get(parent.id) ?? parent.id);
+        }
+      }
+    }
+    return sources;
+  }
+
+  function inferSimple(target: OrderableConstituenta): boolean {
+    if (target.cst_type === CstType.STRUCTURED || isBaseSet(target.cst_type)) {
+      return false;
+    }
+    const dependencies = graph.at(target.id)?.inputs ?? [];
+    if (dependencies.some(id => isTemplate.get(id) && !isSimple.get(id))) {
+      return false;
+    }
+    const expression = isFunctional(target.cst_type)
+      ? splitTemplateDefinition(target.definition_formal).body
+      : target.definition_formal;
+    return isSimpleExpression(expression);
+  }
+
+  for (const cstId of graph.topologicalOrder()) {
+    const cst = byId.get(cstId);
+    if (!cst) {
+      continue;
+    }
+    isTemplate.set(cstId, inferTemplate(cst.definition_formal));
+    isSimple.set(cstId, inferSimple(cst));
+    if (!isSimple.get(cstId) || cst.cst_type === CstType.STRUCTURED) {
+      continue;
+    }
+    const sources = extractSources(cst);
+    if (sources.size !== 1) {
+      continue;
+    }
+    const parentId = [...sources][0];
+    const parent = byId.get(parentId);
+    if (!parent || isBaseSet(parent.cst_type)) {
+      continue;
+    }
+    parentOf.set(cstId, parentId);
+    childrenOf.get(parentId)!.push(cstId);
+  }
+
+  return { parentOf, childrenOf };
+}

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

@@ -0,0 +1,170 @@
+/**
+ * Schema-level statistics and issue flags.
+ */
+
+import { TypeID, type Typification, ValueClass } from '../../rslang';
+import { hasCstDiagnostic, RSDiagnosticCode } from '../diagnostics';
+import { type Constituenta, CstStatus, CstType, type RSForm, type RSFormStats } from '../rsform';
+
+import { isBasicConcept, isLogical } from './cst-type';
+
+/** Checks if {@link Constituenta} is a schema issue. */
+export function isSchemaIssue(cst: Constituenta): boolean {
+  return (
+    (cst.diagnostics?.length ?? 0) > 0 || cst.status === CstStatus.INCORRECT || cst.status === CstStatus.INCALCULABLE
+  );
+}
+
+/** Calculate statistics for {@link RSForm}. */
+export function calculateSchemaStats(target: RSForm): RSFormStats {
+  const stats: RSFormStats = {
+    count_all: target.items.length,
+    count_crucial: 0,
+    step_complexity: 0,
+    count_problematic: 0,
+    count_homonyms: 0,
+    count_formal_duplicates: 0,
+    count_missing_basic_text: 0,
+    count_type_mismatch: 0,
+    count_incorrect: 0,
+    count_property: 0,
+    count_incalculable: 0,
+    count_inherited: 0,
+    count_text_term: 0,
+    count_definition: 0,
+    count_convention: 0,
+    count_comment: 0,
+    count_base: 0,
+    count_constant: 0,
+    count_structured: 0,
+    count_axiom: 0,
+    count_term: 0,
+    count_function: 0,
+    count_predicate: 0,
+    count_statement: 0,
+    count_nominal: 0
+  };
+
+  for (const cst of target.items) {
+    if (cst.crucial) {
+      stats.count_crucial += 1;
+    }
+    stats.step_complexity += calculateStepComplexity(cst);
+
+    if (isSchemaIssue(cst)) {
+      stats.count_problematic += 1;
+    }
+    if (hasCstDiagnostic(cst, RSDiagnosticCode.schemaHomonym)) {
+      stats.count_homonyms += 1;
+    }
+    if (hasCstDiagnostic(cst, RSDiagnosticCode.schemaFormalDuplicate)) {
+      stats.count_formal_duplicates += 1;
+    }
+    if (isMissingBasicText(cst)) {
+      stats.count_missing_basic_text += 1;
+    }
+    if (cst.is_type_mismatch) {
+      stats.count_type_mismatch += 1;
+    }
+    if (cst.status === CstStatus.INCORRECT) {
+      stats.count_incorrect += 1;
+    }
+    if (cst.analysis?.valueClass === ValueClass.PROPERTY) {
+      stats.count_property += 1;
+    }
+    if (cst.analysis?.success && cst.analysis.valueClass === null) {
+      stats.count_incalculable += 1;
+    }
+    if (cst.is_inherited) {
+      stats.count_inherited += 1;
+    }
+    if (cst.term_raw) {
+      stats.count_text_term += 1;
+    }
+    if (cst.definition_raw) {
+      stats.count_definition += 1;
+    }
+    if (isBasicConcept(cst.cst_type) && cst.convention) {
+      stats.count_convention += 1;
+    }
+    if (!isBasicConcept(cst.cst_type) && !cst.convention) {
+      stats.count_comment += 1;
+    }
+
+    switch (cst.cst_type) {
+      case CstType.BASE:
+        stats.count_base += 1;
+        break;
+      case CstType.CONSTANT:
+        stats.count_constant += 1;
+        break;
+      case CstType.STRUCTURED:
+        stats.count_structured += 1;
+        break;
+      case CstType.AXIOM:
+        stats.count_axiom += 1;
+        break;
+      case CstType.TERM:
+        stats.count_term += 1;
+        break;
+      case CstType.FUNCTION:
+        stats.count_function += 1;
+        break;
+      case CstType.PREDICATE:
+        stats.count_predicate += 1;
+        break;
+      case CstType.STATEMENT:
+        stats.count_statement += 1;
+        break;
+      case CstType.NOMINAL:
+        stats.count_nominal += 1;
+        break;
+    }
+  }
+
+  return stats;
+}
+
+function calculateStepComplexity(cst: Constituenta): number {
+  if (cst.cst_type === CstType.AXIOM || cst.cst_type === CstType.NOMINAL || !isBasicConcept(cst.cst_type)) {
+    return 0;
+  }
+  if (cst.cst_type === CstType.BASE || cst.cst_type === CstType.CONSTANT || !cst.effectiveType) {
+    return 1;
+  }
+
+  const type = cst.effectiveType as Typification;
+  return calculateTypificationComplexity(type) + 1;
+}
+
+function calculateTypificationComplexity(type: Typification): number {
+  switch (type.typeID) {
+    case TypeID.basic:
+    case TypeID.integer:
+    case TypeID.anyTypification:
+      return 0;
+    case TypeID.tuple:
+      return (
+        type.factors.length + type.factors.reduce((sum, factor) => sum + calculateTypificationComplexity(factor), 0)
+      );
+    case TypeID.collection:
+      if (type.base.typeID === TypeID.tuple) {
+        let sum = 0;
+        type.base.factors.forEach(factor => {
+          sum += calculateTypificationComplexity(factor);
+        });
+        return sum + type.base.factors.length;
+      } else if (type.base.typeID === TypeID.collection) {
+        return calculateTypificationComplexity(type.base) + 1;
+      }
+      return 0;
+  }
+}
+
+/** Non-logical basic concept missing convention and/or resolved term (trimmed). */
+function isMissingBasicText(cst: Constituenta): boolean {
+  if (!isBasicConcept(cst.cst_type) || isLogical(cst.cst_type)) {
+    return false;
+  }
+  return !cst.convention.trim() || !cst.term_resolved.trim();
+}

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

@@ -0,0 +1,93 @@
+/**
+ * Structure-path helpers for spawned constituents.
+ */
+
+import { TypeID, type TypePath, type Typification } from '../../rslang';
+import { isTypification } from '../../rslang/semantic/typification';
+import { applyPath } from '../../rslang/semantic/typification-api';
+import { type Constituenta, type RSForm } from '../rsform';
+
+/**
+ * Id to pass as `insert_after` when creating a new {@link Constituenta} spawned by `targetId`:
+ * after the last existing child of that spawner, or after the spawner itself if none.
+ */
+export function inferNewSpawnPosition(schema: RSForm, targetId: number): number {
+  let last: number | null = null;
+  for (const cst of schema.items) {
+    if (cst.spawner === targetId) {
+      last = cst.id;
+    }
+  }
+  return last ?? targetId;
+}
+
+/** Finds {@link Constituenta} by structure path. */
+export function findCstByStructure(schema: RSForm, target: Constituenta, path: TypePath): Constituenta | null {
+  const byId = schema.cstByID ?? new Map(schema.items.map(item => [item.id, item]));
+  for (const cst of schema.items) {
+    if (!cst.spawner_path) {
+      continue;
+    }
+    const absolutePath = resolveAbsoluteSpawnerPath(cst, target.id, byId);
+    if (absolutePath?.length === path.length && absolutePath.every((v, i) => v === path[i])) {
+      return cst;
+    }
+  }
+  return null;
+}
+
+/** Retrieves name for piece of target {@link Constituenta} structure. */
+export function getStructureName(schema: RSForm, target: Constituenta, path: TypePath): string {
+  const representation = findCstByStructure(schema, target, path);
+  if (representation) {
+    return `${representation.alias}: ${representation.term_resolved}`;
+  }
+  if (!isTypification(target.effectiveType)) {
+    return '';
+  }
+  const type = applyPath(target.effectiveType as Typification, path);
+  if (type?.typeID === TypeID.basic) {
+    const cst = schema.cstByAlias.get(type.baseID);
+    if (cst?.term_resolved) {
+      return `${cst.alias}: ${cst.term_resolved}`;
+    }
+  }
+  return '';
+}
+
+function resolveAbsoluteSpawnerPath(
+  cst: Constituenta,
+  targetId: number,
+  byId: Map<number, Constituenta>
+): TypePath | null {
+  if (!cst.spawner_path || cst.spawner == null) {
+    return null;
+  }
+  if (cst.spawner === targetId) {
+    return cst.spawner_path;
+  }
+
+  const visited = new Set<number>([cst.id]);
+  let currentPath: number[] = [...cst.spawner_path];
+  let currentSpawnerId: number | null = cst.spawner;
+
+  while (currentSpawnerId != null) {
+    if (currentSpawnerId === targetId) {
+      return currentPath as TypePath;
+    }
+    if (visited.has(currentSpawnerId)) {
+      return null;
+    }
+    visited.add(currentSpawnerId);
+
+    const parent = byId.get(currentSpawnerId);
+    if (!parent?.spawner_path || parent.spawner == null) {
+      return null;
+    }
+
+    currentPath = [...parent.spawner_path, ...currentPath];
+    currentSpawnerId = parent.spawner;
+  }
+
+  return null;
+}

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] };
+  });
+}