Socrates/apps/web/lib/sysml/crossValidate.ts

// Cross-layer validation — checks the joins between taxonomy/glossary terms
// and the SysML ontology. These rules run separately from the structural
// SysML validator (validate.ts) because they need access to the term list,
// which validate.ts deliberately doesn't know about.
//
// Rule codes are prefixed `X*` to distinguish them from S/M/T rules and to
// make it easy for the FindingsPane to render them under their own group.
//
// Severities: X1 and X3 are warnings (the data is in a broken state and the
// user almost certainly wants to fix it). X2 and X4 are soft hints — they
// surface opportunities to formalize without being intrusive.

import type { ValidationIssue } from "./validate";
import type { SysMLModel } from "./model";

export interface CrossTerm {
  id: string;
  label: string;
  linkedBlockId: string | null;
}

export interface CrossValidateInput {
  model: SysMLModel;
  terms: CrossTerm[];
  /** How many times each term occurs in the prose document.
   *  Optional — when absent, X4 is skipped. */
  occurrencesByTermId?: Record<string, number>;
}

/** Threshold for X4: surface a "consider promoting" hint only when a term
 *  appears at least this many times in prose. Tuned to avoid spam on
 *  one-off mentions. */
export const X4_OCCURRENCE_THRESHOLD = 3;

export function crossValidate(input: CrossValidateInput): ValidationIssue[] {
  const { model, terms, occurrencesByTermId } = input;
  const issues: ValidationIssue[] = [];

  const termById = new Map(terms.map(t => [t.id, t]));
  const blockById = new Map(model.blocks.map(b => [b.id, b]));

  // ─── X1 — element.linkedTermId points to a missing term ─────────────────

  for (const b of model.blocks) {
    if (b.linkedTermId && !termById.has(b.linkedTermId)) {
      issues.push({
        code: "X1",
        severity: "warning",
        message: `Block "${b.label}" links to a term that no longer exists`,
        anchor: { kind: "block", id: b.id },
      });
    }
  }
  for (const a of model.associations) {
    if (a.linkedTermId && !termById.has(a.linkedTermId)) {
      issues.push({
        code: "X1",
        severity: "warning",
        message: `Association "${a.label || a.id}" links to a term that no longer exists`,
        anchor: { kind: "association", id: a.id },
      });
    }
  }
  for (const c of model.constraints) {
    if (c.linkedTermId && !termById.has(c.linkedTermId)) {
      issues.push({
        code: "X1",
        severity: "warning",
        message: `Constraint "${c.label}" links to a term that no longer exists`,
        anchor: { kind: "constraint", id: c.id },
      });
    }
  }
  for (const r of model.requirements) {
    if (r.linkedTermId && !termById.has(r.linkedTermId)) {
      issues.push({
        code: "X1",
        severity: "warning",
        message: `Requirement ${r.tag} links to a term that no longer exists`,
        anchor: { kind: "requirement", id: r.id },
      });
    }
  }

  // ─── X2 — formalism has no linkedTermId (soft hint) ─────────────────────

  for (const b of model.blocks) {
    if (!b.linkedTermId) {
      issues.push({
        code: "X2",
        severity: "soft",
        message: `Block "${b.label}" is not anchored to a concept — naming it after a term keeps the model in sync with the document`,
        anchor: { kind: "block", id: b.id },
      });
    }
  }

  // ─── X3 — term.linkedBlockId is stale (block was deleted) ───────────────

  for (const t of terms) {
    if (t.linkedBlockId && !blockById.has(t.linkedBlockId)) {
      issues.push({
        code: "X3",
        severity: "warning",
        message: `Concept "${t.label}" links to a block that no longer exists`,
        anchor: { kind: "term", id: t.id },
      });
    }
  }

  // ─── X4 — prose-frequent term not formalized anywhere ───────────────────

  if (occurrencesByTermId) {
    const formalizedTermIds = new Set<string>();
    for (const b of model.blocks) if (b.linkedTermId) formalizedTermIds.add(b.linkedTermId);
    for (const a of model.associations) if (a.linkedTermId) formalizedTermIds.add(a.linkedTermId);
    for (const c of model.constraints) if (c.linkedTermId) formalizedTermIds.add(c.linkedTermId);
    for (const r of model.requirements) if (r.linkedTermId) formalizedTermIds.add(r.linkedTermId);

    for (const t of terms) {
      const n = occurrencesByTermId[t.id] ?? 0;
      if (n < X4_OCCURRENCE_THRESHOLD) continue;
      if (formalizedTermIds.has(t.id)) continue;
      issues.push({
        code: "X4",
        severity: "soft",
        message: `Concept "${t.label}" appears ${n}× in prose but has no formalization — consider promoting it`,
        anchor: { kind: "term", id: t.id },
      });
    }
  }

  return issues;
}