@rsconcept/domain 2.0.1 → 2.1.0

package/src/graph/graph.ts

@@ -379,7 +379,7 @@ export class Graph<NodeID = number> {
    * Finds a cycle in the graph.
    *
    * @returns {NodeID[] | null} The cycle if found, otherwise `null`.
-   * Uses non-recursive DFS.
+   * Uses non-recursive DFS. The returned path is closed (first id equals last).
    */
   findCycle(): NodeID[] | null {
     const visited = new Set<NodeID>();
@@ -430,4 +430,108 @@ export class Graph<NodeID = number> {
     }
     return null;
   }
+
+  /**
+   * Finds one closed cycle path per cyclic strongly connected component.
+   *
+   * @returns Closed paths (first id equals last). Empty when the graph is acyclic.
+   */
+  findCycles(): NodeID[][] {
+    const components = this.stronglyConnectedComponents();
+    const result: NodeID[][] = [];
+    for (const component of components) {
+      if (component.length === 1) {
+        const id = component[0];
+        if (this.hasEdge(id, id)) {
+          result.push([id, id]);
+        }
+        continue;
+      }
+      const subgraph = new Graph<NodeID>();
+      const memberIds = new Set(component);
+      for (const id of component) {
+        subgraph.addNode(id);
+        const node = this.nodes.get(id);
+        if (!node) {
+          continue;
+        }
+        for (const child of node.outputs) {
+          if (memberIds.has(child)) {
+            subgraph.addEdge(id, child);
+          }
+        }
+      }
+      const cycle = subgraph.findCycle();
+      if (cycle) {
+        result.push(cycle);
+      }
+    }
+    return result;
+  }
+
+  /** Tarjan strongly connected components (non-recursive). */
+  stronglyConnectedComponents(): NodeID[][] {
+    let index = 0;
+    const indices = new Map<NodeID, number>();
+    const lowlink = new Map<NodeID, number>();
+    const onStack = new Set<NodeID>();
+    const stack: NodeID[] = [];
+    const components: NodeID[][] = [];
+
+    type Frame = { nodeId: NodeID; edgeIndex: number; entered: boolean };
+    for (const startId of this.nodes.keys()) {
+      if (indices.has(startId)) {
+        continue;
+      }
+      const callStack: Frame[] = [{ nodeId: startId, edgeIndex: 0, entered: false }];
+      while (callStack.length > 0) {
+        const frame = callStack[callStack.length - 1];
+        const node = this.nodes.get(frame.nodeId);
+        if (!node) {
+          callStack.pop();
+          continue;
+        }
+
+        if (!frame.entered) {
+          frame.entered = true;
+          indices.set(frame.nodeId, index);
+          lowlink.set(frame.nodeId, index);
+          index += 1;
+          stack.push(frame.nodeId);
+          onStack.add(frame.nodeId);
+        }
+
+        if (frame.edgeIndex < node.outputs.length) {
+          const child = node.outputs[frame.edgeIndex];
+          frame.edgeIndex += 1;
+          if (!indices.has(child)) {
+            callStack.push({ nodeId: child, edgeIndex: 0, entered: false });
+          } else if (onStack.has(child)) {
+            lowlink.set(frame.nodeId, Math.min(lowlink.get(frame.nodeId)!, indices.get(child)!));
+          }
+          continue;
+        }
+
+        callStack.pop();
+        if (callStack.length > 0) {
+          const parentId = callStack[callStack.length - 1].nodeId;
+          lowlink.set(parentId, Math.min(lowlink.get(parentId)!, lowlink.get(frame.nodeId)!));
+        }
+
+        if (lowlink.get(frame.nodeId) === indices.get(frame.nodeId)) {
+          const component: NodeID[] = [];
+          while (stack.length > 0) {
+            const id = stack.pop()!;
+            onStack.delete(id);
+            component.push(id);
+            if (id === frame.nodeId) {
+              break;
+            }
+          }
+          components.push(component);
+        }
+      }
+    }
+    return components;
+  }
 }

package/src/index.ts

@@ -11,7 +11,9 @@ export { Graph } from './graph/graph';
 export {
   assignSchemaDiagnostics,
   type CstDiagnostic,
+  detectDependencyCycleDiagnostics,
   DiagnosticKind,
+  formatDependencyCycle,
   hasCstDiagnostic,
   modelStatusCstDiagnostic,
   RSDiagnosticCode

package/src/library/diagnostics.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest';
+
+import { Graph } from '../graph';
+
+import {
+  assignSchemaDiagnostics,
+  DiagnosticKind,
+  formatDependencyCycle,
+  hasCstDiagnostic,
+  modelStatusCstDiagnostic,
+  RSDiagnosticCode
+} from './diagnostics';
+import { type Constituenta, CstType } from './rsform';
+import { EvalStatus } from './rsmodel';
+
+function stubCst(id: number, alias: string, overrides: Partial<Constituenta> = {}): Constituenta {
+  return {
+    id,
+    alias,
+    term_resolved: '',
+    definition_formal: '',
+    convention: '',
+    cst_type: CstType.BASE,
+    is_type_mismatch: false,
+    typification_manual: '',
+    analysis: { success: true, type: null },
+    diagnostics: [],
+    ...overrides
+  } as Constituenta;
+}
+
+describe('hasCstDiagnostic', () => {
+  it('returns true when constituent has the requested code', () => {
+    const cst = stubCst(1, 'X1', {
+      diagnostics: [{ kind: DiagnosticKind.SCHEMA, code: RSDiagnosticCode.schemaHomonym, params: ['X2'] }]
+    });
+    expect(hasCstDiagnostic(cst, RSDiagnosticCode.schemaHomonym)).toBe(true);
+    expect(hasCstDiagnostic(cst, RSDiagnosticCode.schemaFormalDuplicate)).toBe(false);
+  });
+
+  it('returns false when diagnostics are absent', () => {
+    expect(hasCstDiagnostic(stubCst(1, 'X1'), RSDiagnosticCode.schemaHomonym)).toBe(false);
+  });
+});
+
+describe('modelStatusCstDiagnostic', () => {
+  it('maps model evaluation statuses to compact diagnostics', () => {
+    expect(modelStatusCstDiagnostic(EvalStatus.EMPTY, CstType.BASE)).toEqual({
+      kind: DiagnosticKind.MODEL,
+      code: RSDiagnosticCode.modelEmpty,
+      params: [String(EvalStatus.EMPTY)]
+    });
+    expect(modelStatusCstDiagnostic(EvalStatus.AXIOM_FALSE, CstType.AXIOM)).toEqual({
+      kind: DiagnosticKind.MODEL,
+      code: RSDiagnosticCode.modelAxiomFalse,
+      params: [String(EvalStatus.AXIOM_FALSE)]
+    });
+    expect(modelStatusCstDiagnostic(EvalStatus.HAS_DATA, CstType.BASE)).toBeNull();
+    expect(modelStatusCstDiagnostic(EvalStatus.EMPTY, CstType.TERM)).toBeNull();
+  });
+});
+
+describe('assignSchemaDiagnostics', () => {
+  it('detects homonyms and formal duplicates', () => {
+    const items = [
+      stubCst(1, 'X1', { term_resolved: 'person' }),
+      stubCst(2, 'X2', { term_resolved: 'Person' }),
+      stubCst(3, 'D1', { cst_type: CstType.TERM, definition_formal: 'Pr1(X1)' }),
+      stubCst(4, 'D2', { cst_type: CstType.TERM, definition_formal: 'Pr1(X1)' })
+    ];
+    const resolveAlias = (id: number) => items.find(item => item.id === id)!.alias;
+    const normalizedDefinitions = new Map<number, string>([
+      [3, 'pr1(x1)'],
+      [4, 'pr1(x1)']
+    ]);
+
+    assignSchemaDiagnostics(items, resolveAlias, normalizedDefinitions);
+
+    expect(hasCstDiagnostic(items[0], RSDiagnosticCode.schemaHomonym)).toBe(true);
+    expect(items[0].diagnostics.find(item => item.code === RSDiagnosticCode.schemaHomonym)?.params?.[0]).toBe('X2');
+    expect(hasCstDiagnostic(items[1], RSDiagnosticCode.schemaHomonym)).toBe(true);
+    expect(items[1].diagnostics.find(item => item.code === RSDiagnosticCode.schemaHomonym)?.params?.[0]).toBe('X1');
+    expect(hasCstDiagnostic(items[2], RSDiagnosticCode.schemaFormalDuplicate)).toBe(true);
+    expect(items[2].diagnostics.find(item => item.code === RSDiagnosticCode.schemaFormalDuplicate)?.params?.[0]).toBe(
+      'D2'
+    );
+  });
+
+  it('detects dependency cycles when graph is provided', () => {
+    const items = [
+      stubCst(1, 'F3', { cst_type: CstType.TERM, definition_formal: 'P1' }),
+      stubCst(2, 'P1', { cst_type: CstType.AXIOM, definition_formal: 'F3' }),
+      stubCst(3, 'X1', { convention: 'base', term_resolved: 'base' })
+    ];
+    const graph = new Graph([[1, 2], [2, 1], [3]]);
+    const resolveAlias = (id: number) => items.find(item => item.id === id)!.alias;
+
+    assignSchemaDiagnostics(items, resolveAlias, new Map(), graph);
+
+    expect(hasCstDiagnostic(items[0], RSDiagnosticCode.schemaDependencyCycle)).toBe(true);
+    expect(hasCstDiagnostic(items[1], RSDiagnosticCode.schemaDependencyCycle)).toBe(true);
+    expect(hasCstDiagnostic(items[2], RSDiagnosticCode.schemaDependencyCycle)).toBe(false);
+    const cycle = items[0].diagnostics.find(item => item.code === RSDiagnosticCode.schemaDependencyCycle)?.params?.[0];
+    expect(cycle).toBeDefined();
+    expect(cycle!.includes('F3')).toBe(true);
+    expect(cycle!.includes('P1')).toBe(true);
+    expect(cycle!.startsWith(cycle!.split(' → ').at(-1)!)).toBe(true);
+  });
+});
+
+describe('formatDependencyCycle', () => {
+  it('joins aliases with arrows', () => {
+    expect(formatDependencyCycle(['F3', 'P1', 'F3'])).toBe('F3 → P1 → F3');
+  });
+});

package/src/library/diagnostics.ts

@@ -2,6 +2,7 @@
  * Module: Compact diagnostics for constituents (schema and model issue codes).
  */
 
+import { type Graph } from '../graph';
 import { labelType } from '../rslang/labels';
 
 import { type Constituenta, type CstType } from './rsform';
@@ -23,6 +24,7 @@ export const RSDiagnosticCode = {
   schemaMissingConvention: 0x8903,
   schemaMissingTerm: 0x8904,
   schemaTypeMismatch: 0x8905,
+  schemaDependencyCycle: 0x8906,
 
   modelEmpty: 0x8910,
   modelAxiomFalse: 0x8911,
@@ -45,20 +47,27 @@ export function hasCstDiagnostic(cst: Constituenta, code: RSDiagnosticCode): boo
 }
 
 /**
- * Populate `diagnostics` on each constituent (homonyms, duplicates, metadata, type mismatch).
+ * Populate `diagnostics` on each constituent (homonyms, duplicates, metadata, type mismatch, cycles).
  *
  * Requires normalized formal definitions for duplicate detection (same as Portal loader).
+ * When `graph` is provided, dependency cycles are reported as {@link RSDiagnosticCode.schemaDependencyCycle}.
  */
 export function assignSchemaDiagnostics(
   items: Constituenta[],
   resolveAlias: (id: number) => string,
-  normalizedDefinitions: ReadonlyMap<number, string>
+  normalizedDefinitions: ReadonlyMap<number, string>,
+  graph?: Graph
 ): void {
   const homonymById = detectHomonymDiagnostics(items, resolveAlias);
   const duplicateById = detectFormalDuplicateDiagnostics(items, resolveAlias, normalizedDefinitions);
+  const cycleById = graph ? detectDependencyCycleDiagnostics(graph, resolveAlias) : new Map<number, CstDiagnostic>();
 
   for (const cst of items) {
     const diagnostics: CstDiagnostic[] = [];
+    const cycle = cycleById.get(cst.id);
+    if (cycle) {
+      diagnostics.push(cycle);
+    }
     const homonym = homonymById.get(cst.id);
     if (homonym) {
       diagnostics.push(homonym);
@@ -72,6 +81,38 @@ export function assignSchemaDiagnostics(
   }
 }
 
+/** Format a closed cycle of aliases as `A → B → A`. */
+export function formatDependencyCycle(aliases: readonly string[]): string {
+  return aliases.join(' → ');
+}
+
+/**
+ * Map each node id that participates in a dependency cycle to a schema diagnostic.
+ * `params[0]` is the closed cycle path (`F3 → P1 → F3`).
+ */
+export function detectDependencyCycleDiagnostics(
+  graph: Graph,
+  resolveAlias: (id: number) => string
+): Map<number, CstDiagnostic> {
+  const result = new Map<number, CstDiagnostic>();
+  for (const cycle of graph.findCycles()) {
+    if (cycle.length < 2) {
+      continue;
+    }
+    const aliases = cycle.map(id => resolveAlias(id));
+    const cycleText = formatDependencyCycle(aliases);
+    const memberIds = new Set(cycle);
+    for (const id of memberIds) {
+      result.set(id, {
+        kind: DiagnosticKind.SCHEMA,
+        code: RSDiagnosticCode.schemaDependencyCycle,
+        params: [cycleText]
+      });
+    }
+  }
+  return result;
+}
+
 /** Map a model evaluation status to a compact diagnostic, or `null` when not an issue. */
 export function modelStatusCstDiagnostic(status: EvalStatus, cstType: CstType): CstDiagnostic | null {
   const code = modelStatusToCode(status, cstType);
@@ -101,23 +142,25 @@ function collectLocalSchemaDiagnostics(cst: Constituenta): CstDiagnostic[] {
   return result;
 }
 
-function detectHomonymDiagnostics(
+function detectGroupedAliasDiagnostics(
   items: Constituenta[],
-  resolveAlias: (id: number) => string
+  resolveAlias: (id: number) => string,
+  groupKey: (cst: Constituenta) => string | undefined,
+  code: RSDiagnosticCode
 ): Map<number, CstDiagnostic> {
-  const byTerm = new Map<string, Constituenta[]>();
+  const groups = new Map<string, Constituenta[]>();
   for (const cst of items) {
-    const key = cst.term_resolved.trim().toLocaleLowerCase();
-    if (key === '') {
+    const key = groupKey(cst);
+    if (!key) {
       continue;
     }
-    const group = byTerm.get(key) ?? [];
+    const group = groups.get(key) ?? [];
     group.push(cst);
-    byTerm.set(key, group);
+    groups.set(key, group);
   }
 
   const result = new Map<number, CstDiagnostic>();
-  for (const group of byTerm.values()) {
+  for (const group of groups.values()) {
     if (group.length <= 1) {
       continue;
     }
@@ -128,7 +171,7 @@ function detectHomonymDiagnostics(
         .join(', ');
       result.set(cst.id, {
         kind: DiagnosticKind.SCHEMA,
-        code: RSDiagnosticCode.schemaHomonym,
+        code,
         params: [aliases]
       });
     }
@@ -136,40 +179,32 @@ function detectHomonymDiagnostics(
   return result;
 }
 
+function detectHomonymDiagnostics(
+  items: Constituenta[],
+  resolveAlias: (id: number) => string
+): Map<number, CstDiagnostic> {
+  return detectGroupedAliasDiagnostics(
+    items,
+    resolveAlias,
+    cst => {
+      const key = cst.term_resolved.trim().toLocaleLowerCase();
+      return key === '' ? undefined : key;
+    },
+    RSDiagnosticCode.schemaHomonym
+  );
+}
+
 function detectFormalDuplicateDiagnostics(
   items: Constituenta[],
   resolveAlias: (id: number) => string,
   normalizedDefinitions: ReadonlyMap<number, string>
 ): Map<number, CstDiagnostic> {
-  const byDefinition = new Map<string, Constituenta[]>();
-  for (const cst of items) {
-    const key = normalizedDefinitions.get(cst.id);
-    if (!key) {
-      continue;
-    }
-    const group = byDefinition.get(key) ?? [];
-    group.push(cst);
-    byDefinition.set(key, group);
-  }
-
-  const result = new Map<number, CstDiagnostic>();
-  for (const group of byDefinition.values()) {
-    if (group.length <= 1) {
-      continue;
-    }
-    for (const cst of group) {
-      const aliases = group
-        .filter(other => other.id !== cst.id)
-        .map(other => resolveAlias(other.id))
-        .join(', ');
-      result.set(cst.id, {
-        kind: DiagnosticKind.SCHEMA,
-        code: RSDiagnosticCode.schemaFormalDuplicate,
-        params: [aliases]
-      });
-    }
-  }
-  return result;
+  return detectGroupedAliasDiagnostics(
+    items,
+    resolveAlias,
+    cst => normalizedDefinitions.get(cst.id),
+    RSDiagnosticCode.schemaFormalDuplicate
+  );
 }
 
 function modelStatusToCode(status: EvalStatus, cstType: CstType): RSDiagnosticCode | null {

package/src/library/index.ts

@@ -1,7 +1,9 @@
 export {
   assignSchemaDiagnostics,
   type CstDiagnostic,
+  detectDependencyCycleDiagnostics,
   DiagnosticKind,
+  formatDependencyCycle,
   hasCstDiagnostic,
   modelStatusCstDiagnostic,
   RSDiagnosticCode

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

@@ -1,9 +1,18 @@
 import { describe, expect, it } from 'vitest';
 
+import { Graph } from '../graph';
 import { RSErrorCode } from '../rslang/error';
-
-import { CstType, type RSForm } from './rsform';
-import { applyMappingToConstituents, getAnalysisFor, normalizeExpression, validateAliasFormat } from './rsform-api';
+import { RSLangAnalyzer } from '../rslang/semantic/analyzer';
+
+import { RSDiagnosticCode } from './diagnostics';
+import { type Constituenta, CstType, type RSForm } from './rsform';
+import {
+  applyMappingToConstituents,
+  findCstByStructure,
+  getAnalysisFor,
+  normalizeExpression,
+  validateAliasFormat
+} from './rsform-api';
 
 const emptySchema = {} as RSForm;
 
@@ -49,6 +58,56 @@ describe('getAnalysisFor', () => {
       params: [CstType.CONSTANT, 'C1']
     });
   });
+
+  it('upgrades to dependency cycle for unsaved draft that closes a cycle', () => {
+    // Saved graph: F3 → P1 only (P1 does not yet reference F3).
+    // Draft for P1 introduces F3, closing F3 ↔ P1 before Save.
+    const analyzer = new RSLangAnalyzer();
+    analyzer.addBase('X1');
+    // F3 is untyped in the analyzer (as after a failed cycle parse), so P1's call fails.
+    const items = [
+      {
+        id: 1,
+        alias: 'X1',
+        cst_type: CstType.BASE,
+        definition_formal: '',
+        diagnostics: []
+      },
+      {
+        id: 2,
+        alias: 'F3',
+        cst_type: CstType.FUNCTION,
+        definition_formal: '[σ∈X1] P1[σ]',
+        diagnostics: []
+      },
+      {
+        id: 3,
+        alias: 'P1',
+        cst_type: CstType.PREDICATE,
+        definition_formal: '[σ∈X1] σ=σ',
+        diagnostics: []
+      }
+    ] as unknown as Constituenta[];
+    const graph = new Graph([
+      [1, 2],
+      [1, 3],
+      [3, 2] // P1 → F3 from saved F3 definition
+    ]);
+    const schema = {
+      items,
+      graph,
+      analyzer,
+      cstByAlias: new Map(items.map(item => [item.alias, item])),
+      cstByID: new Map(items.map(item => [item.id, item]))
+    } as unknown as RSForm;
+
+    const draft = '[σ∈X1] F3[σ]=F3[σ]';
+    const result = getAnalysisFor(draft, CstType.PREDICATE, schema, 'P1');
+    const cycleError = result.errors.find(error => error.code === RSDiagnosticCode.schemaDependencyCycle);
+    expect(cycleError).toBeDefined();
+    expect(cycleError!.params?.[0]).toContain('F3');
+    expect(cycleError!.params?.[0]).toContain('P1');
+  });
 });
 
 describe('applyMappingToConstituents', () => {
@@ -98,3 +157,40 @@ describe('normalizeExpression', () => {
     expect(normalizeExpression('ℬ(X1)', CstType.STRUCTURED)).toBeNull();
   });
 });
+
+describe('findCstByStructure', () => {
+  function makeProjectionChainSchema() {
+    const s1 = { id: 1, alias: 'S1' };
+    const d1 = { id: 2, alias: 'D1', spawner: 1, spawner_path: [0, 1] };
+    const d2 = { id: 3, alias: 'D2', spawner: 2, spawner_path: [2] };
+    const d3 = { id: 4, alias: 'D3', spawner: 3, spawner_path: [1] };
+    const d4 = { id: 5, alias: 'D4', spawner: 4, spawner_path: [2] };
+    const schema = {
+      items: [s1, d1, d2, d3, d4],
+      cstByID: new Map([
+        [1, s1],
+        [2, d1],
+        [3, d2],
+        [4, d3],
+        [5, d4]
+      ])
+    } as unknown as RSForm;
+    return { schema, s1, d1, d2, d3, d4 };
+  }
+
+  it('resolves chain of relative projection paths to root target', () => {
+    const { schema, s1, d2 } = makeProjectionChainSchema();
+
+    expect(findCstByStructure(schema, s1 as never, [0, 1, 2] as never)).toBe(d2);
+  });
+
+  it('resolves a four-step projection chain from the root structure', () => {
+    const { schema, s1, d1, d2, d3, d4 } = makeProjectionChainSchema();
+
+    expect(findCstByStructure(schema, s1 as never, [0, 1] as never)).toBe(d1);
+    expect(findCstByStructure(schema, s1 as never, [0, 1, 2] as never)).toBe(d2);
+    expect(findCstByStructure(schema, s1 as never, [0, 1, 2, 1] as never)).toBe(d3);
+    expect(findCstByStructure(schema, s1 as never, [0, 1, 2, 1, 2] as never)).toBe(d4);
+    expect(findCstByStructure(schema, s1 as never, [0, 1, 2, 2] as never)).toBeNull();
+  });
+});