speclogician 0.0.0b1__py3-none-any.whl

speclogician/modeling/spec.py

@@ -0,0 +1,306 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/modeling/spec.py
+#
+
+from typing import Optional
+from pydantic import BaseModel, Field
+from collections import defaultdict
+
+from .domain import DomainModel
+from .complement import ScenarioComplement
+from .scenario import Scenario, ScenarioDelta
+from .conflict import ScenarioConflict
+
+def _scenario_guard_iml(scn) -> str:
+    """
+    given predicates are assumed: pred(s)
+    when predicates are assumed: pred(s)(a) or pred(s, a) style; we generate pred s a.
+    """
+    parts: list[str] = []
+
+    for p in (scn.given or []):
+        p = (p or "").strip()
+        if p:
+            parts.append(f"{p} s")
+
+    for p in (scn.when or []):
+        p = (p or "").strip()
+        if p:
+            parts.append(f"{p} s a")
+
+    return " && ".join(parts) if parts else "true"
+
+
+def _scenario_then_iml(scn) -> str:
+    """
+    then is a list of transition function names.
+    Each transition is assumed: trans(s)(a) -> state; we generate trans s a.
+    Applied sequentially.
+    """
+    thens = [(t or "").strip() for t in (scn.then or []) if (t or "").strip()]
+    if not thens:
+        return "s"
+
+    # Apply transitions in order:
+    # let s1 = t1 s a in let s2 = t2 s1 a in s2
+    lines: list[str] = []
+    cur = "s"
+    for i, tname in enumerate(thens, start=1):
+        nxt = f"s{i}"
+        lines.append(f"let {nxt} = {tname} {cur} a in")
+        cur = nxt
+    lines.append(cur)
+    return "\n  ".join(lines)
+
+
+class Spec(BaseModel):
+    """ Spec is comprised of the Domain Model and a list of Scenarios """
+
+    # Domain model object also has all the relevant stats on the model
+    domain_model : DomainModel = Field(default_factory=DomainModel)
+    
+    # The list of scenarios
+    scenarios : list[Scenario] = Field(default_factory=list[Scenario])
+
+    # Are there conflicts between?
+    scenario_conflicts : list[ScenarioConflict] = Field(default_factory=list[ScenarioConflict])
+
+    # Scenario complement
+    scenario_comp : ScenarioComplement | None = None
+
+    # Scenario stats
+    num_sc_total : int = 0 # Total number of scenarios
+    num_sc_missing : int = 0 # Missing predicates/transitions
+    num_sc_matched : int = 0 # Total number of scenarios matched vs artifacts
+    num_sc_inconsistent : int = 0 # Total number of scenarios inconsistent
+
+    # Conflicts (spec-level)
+    num_sc_conflicted: int = 0   # total conflicts (all kinds)
+    num_sc_overlap: int = 0      # overlap conflicts
+    num_sc_consumed: int = 0     # consumed conflicts
+
+    def conflicts_index(self) -> dict[str, list[ScenarioConflict]]:
+        idx: dict[str, list[ScenarioConflict]] = defaultdict(list)
+        for c in self.scenario_conflicts:
+            idx[c.scenario_name1].append(c)
+            idx[c.scenario_name2].append(c)
+        return dict(idx)
+
+    def conflicts_for(self, scenario_name: str) -> list[ScenarioConflict]:
+        return [
+            c for c in self.scenario_conflicts
+            if c.scenario_name1 == scenario_name or c.scenario_name2 == scenario_name
+        ]
+
+    def scenario_exists (self, name:str) -> bool:
+        """
+        Return True/False if scenario already exists
+        """
+        return any(s.name == name for s in self.scenarios)
+    
+    def find_scenario(self, name: str) -> Optional[Scenario]:
+        """
+        Return the Scenario with the given name, or None if not found.
+        """
+        for s in self.scenarios:
+            if s.name == name:
+                return s
+        return None
+
+    def _apply_delta_strict(
+        self,
+        current: list[str],
+        *,
+        delta: ScenarioDelta,
+        allowed_add: set[str],
+        section_label: str,
+    ) -> list[str]:
+        cur = set(current)
+
+        # --- validate removals: must already be present ---
+        missing_removals = set(delta.remove) - cur
+        if missing_removals:
+            raise ValueError(
+                f"{section_label}: cannot remove names that are not present: {sorted(missing_removals)}"
+            )
+
+        # --- validate additions only ---
+        bad_adds = set(delta.add) - allowed_add
+        if bad_adds:
+            raise ValueError(
+                f"{section_label}: cannot add unknown names: {sorted(bad_adds)}"
+            )
+
+        # optional: forbid adding something already present
+        already_present = set(delta.add) & cur
+        if already_present:
+            raise ValueError(
+                f"{section_label}: names already present: {sorted(already_present)}"
+            )
+
+        # --- apply ---
+        cur.difference_update(delta.remove)
+        cur.update(delta.add)
+
+        return sorted(cur)  # deterministic
+    
+
+    def add_scenario(
+        self,
+        name: str,
+        given: ScenarioDelta | None,
+        when: ScenarioDelta | None,
+        then: ScenarioDelta | None,
+    ) -> None:
+        """Add a new scenario. Deltas must be add-only."""
+        if self.scenario_exists(name):
+            raise ValueError(f"Scenario with this name already exists: [{name}]")
+
+        allowed_given = set(self.domain_model.state_pred_names())
+        allowed_when = set(self.domain_model.action_pred_names())
+        allowed_then = set(self.domain_model.transition_names())
+
+        def build_section(delta: ScenarioDelta | None, allowed: set[str], label: str) -> list[str]:
+            if delta is None:
+                return []
+            if not delta.is_add_only():
+                raise ValueError(f"{label}: 'remove' is not allowed when creating a scenario")
+
+            bad = set(delta.add) - allowed
+            if bad:
+                raise ValueError(f"{label}: cannot add unknown names: {sorted(bad)}")
+
+            return sorted(set(delta.add))  # set semantics, deterministic
+
+        new_given = build_section(given, allowed_given, f"Scenario '{name}' given")
+        new_when  = build_section(when,  allowed_when,  f"Scenario '{name}' when")
+        new_then  = build_section(then,  allowed_then,  f"Scenario '{name}' then")
+
+        self.scenarios.append(
+            Scenario(name=name, given=new_given, when=new_when, then=new_then)
+        )
+
+    def edit_scenario(
+        self,
+        name: str,
+        given: Optional[ScenarioDelta],
+        when: Optional[ScenarioDelta],
+        then: Optional[ScenarioDelta],
+    ) -> None:
+        """Edit an existing scenario with strict validation (checks only on add)."""
+        scenario = self.find_scenario(name)
+        if scenario is None:
+            raise ValueError(f"Scenario '{name}' not found")
+
+        allowed_given = set(self.domain_model.state_pred_names())
+        allowed_when = set(self.domain_model.action_pred_names())
+        allowed_then = set(self.domain_model.transition_names())
+
+        if given is not None:
+            scenario.given = self._apply_delta_strict(
+                list(scenario.given),
+                delta=given,
+                allowed_add=allowed_given,
+                section_label=f"Scenario '{name}' given",
+            )
+
+        if when is not None:
+            scenario.when = self._apply_delta_strict(
+                list(scenario.when),
+                delta=when,
+                allowed_add=allowed_when,
+                section_label=f"Scenario '{name}' when",
+            )
+
+        if then is not None:
+            scenario.then = self._apply_delta_strict(
+                list(scenario.then),
+                delta=then,
+                allowed_add=allowed_then,
+                section_label=f"Scenario '{name}' then",
+            )
+        
+    def rem_scenario(self, name: str) -> None:
+        """Remove a scenario by name."""
+        for i, s in enumerate(self.scenarios):
+            if s.name == name:
+                del self.scenarios[i]
+                return
+        raise ValueError(f"Scenario '{name}' not found")
+
+    def scenario_model(self):
+        """
+        Synthesize a model from the scenarios
+        """
+
+        scenario_logic = ""
+        for s in self.scenarios:
+            scenario_logic += f"{s.full_model_to_iml()}\n"
+
+        model = f"""
+let scenarios (s : state) (a : action) = 
+{scenario_logic} else
+false
+"""
+        return model
+    
+    def _scenarios_main_iml(self) -> str:
+        """
+        Compile scenarios into a single dispatcher function `main`.
+        Scenarios are tried in list order (priority order).
+        """
+        if not self.scenarios:
+            return "let main (s: state) (_a: action) : state = s"
+
+        lines: list[str] = []
+        lines.append("let main (s: state) (a: action) : state =")
+
+        for idx, scn in enumerate(self.scenarios):
+            guard = _scenario_guard_iml(scn)
+            body = _scenario_then_iml(scn)
+
+            kw = "if" if idx == 0 else "else if"
+            lines.append(f"  {kw} {guard} then")
+            # indent body nicely
+            body_lines = body.splitlines() or ["s"]
+            lines.append("    " + "\n    ".join(body_lines))
+
+        lines.append("  else s")
+        return "\n".join(lines)
+
+    def full_model(self) -> str:
+        """
+        Return the full model (base + predicates + transitions + scenarios)
+        as a single executable IML program.
+        """
+        dm = self.domain_model
+
+        parts: list[str] = []
+
+        # 1. Base domain
+        if dm.base:
+            parts.append(dm.base.strip())
+
+        # 2. Predicates
+        if dm.state_preds or dm.action_preds:
+            parts.append("\n(* Predicates *)\n")
+            for p in dm.state_preds:
+                parts.append(p.to_iml().strip())
+            for p in dm.action_preds:
+                parts.append(p.to_iml().strip())
+
+        # 3. Transitions
+        if dm.transitions:
+            parts.append("\n(* Transitions *)\n")
+            for t in dm.transitions:
+                parts.append(t.to_iml().strip())
+
+        # 4. Scenarios
+        if self.scenarios:
+            parts.append("\n(* Scenario dispatcher *)\n")
+            parts.append(self._scenarios_main_iml().strip())
+
+        # Join with clean spacing
+        return "\n\n".join(p for p in parts if p.strip())

speclogician/modeling/spec_stats.py

@@ -0,0 +1,39 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/modeling/spec_stats.py
+#
+
+
+from __future__ import annotations
+
+from speclogician.data.mapping import ArtifactMap
+from speclogician.modeling.conflict import ScenarioConsumed, ScenarioOverlap
+from speclogician.modeling.scenario import Inconsistent, Missing
+from speclogician.modeling.spec import Spec
+
+
+def refresh_spec_stats(spec: Spec, *, art_map: ArtifactMap | None) -> None:
+    # ---- scenarios ----
+    spec.num_sc_total = len(spec.scenarios)
+
+    spec.num_sc_missing = sum(
+        1 for sc in spec.scenarios if isinstance(getattr(sc, "component_status", None), Missing)
+    )
+    spec.num_sc_inconsistent = sum(
+        1 for sc in spec.scenarios if isinstance(getattr(sc, "component_status", None), Inconsistent)
+    )
+
+    # “matched” should be keyed by scenario.comp_id (NOT name)
+    if art_map is None:
+        spec.num_sc_matched = 0
+    else:
+        comp_to_art = getattr(art_map, "comp_to_art_map", {}) or {}
+        spec.num_sc_matched = sum(
+            1 for sc in spec.scenarios if len(comp_to_art.get(sc.comp_id, [])) > 0
+        )
+
+    # ---- conflicts (spec-level) ----
+    spec.num_sc_conflicted = len(spec.scenario_conflicts or [])
+    spec.num_sc_overlap = sum(isinstance(c, ScenarioOverlap) for c in (spec.scenario_conflicts or []))
+    spec.num_sc_consumed = sum(isinstance(c, ScenarioConsumed) for c in (spec.scenario_conflicts or []))

speclogician/presentation/api.py

@@ -0,0 +1,244 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/presentation/api.py
+#
+
+from __future__ import annotations
+
+# --- Controls how we print things out (and also contains some data)
+from speclogician.presentation.ctx import RenderCtx
+
+# --- Underlying models
+from speclogician.modeling.predicates import ActionPredicate, StatePredicate, Transition
+from speclogician.modeling.domain import DomainModel
+from speclogician.modeling.spec import Spec
+from speclogician.modeling.complement import ScenarioComplement
+from speclogician.data.traces import TestTrace, LogTrace
+from speclogician.data.refs import DocRef, SrcCodeRef
+from speclogician.data.container import ArtifactContainer, SmartFindResults
+from speclogician.state.inst import StateInstance
+from speclogician.state.diff import StateDiff
+from speclogician.modeling.scenario import Scenario
+from speclogician.state.recommender import Recommendation
+
+# --- Builders
+from speclogician.presentation.builders.predicate import (
+    build_predicate_pm,
+    build_transition_pm,
+)
+from speclogician.presentation.builders.domain import build_domain_model_pm
+from speclogician.presentation.builders.trace import build_test_trace_pm, build_log_trace_pm
+from speclogician.presentation.builders.spec import build_spec_pm
+from speclogician.presentation.builders.scenario import build_scenario_pm
+from speclogician.presentation.builders.data_artifact import build_doc_ref_pm, build_src_code_ref_pm
+from speclogician.presentation.builders.container import build_artifact_container_pm
+from speclogician.presentation.builders.smart_find import build_smart_find_pm
+from speclogician.presentation.builders.state_instance import build_state_instance_pm
+from speclogician.presentation.builders.state_diff import build_state_diff_pm
+from speclogician.presentation.builders.instances_list import build_instances_list_pm
+from speclogician.presentation.builders.recommendations import build_recommendations_pm
+from speclogician.presentation.builders.scenario_complement import build_scenario_complement_pm
+
+
+# --- Renderers
+from speclogician.presentation.renderers.predicate import (
+    render_predicate,
+    render_transition,
+)
+from speclogician.presentation.renderers.trace import render_test_trace, render_log_trace
+from speclogician.presentation.renderers.domain import render_domain_model
+from speclogician.presentation.renderers.spec import render_spec
+from speclogician.presentation.renderers.scenario import render_scenario
+from speclogician.presentation.renderers.data_artifact import render_doc_ref, render_src_code_ref
+from speclogician.presentation.renderers.container import render_artifact_container
+from speclogician.presentation.renderers.smart_find import render_smart_find
+from speclogician.presentation.renderers.state_instance import render_state_instance
+from speclogician.presentation.renderers.state_diff import render_state_diff
+from speclogician.presentation.renderers.instances_list import render_instances_list
+from speclogician.presentation.renderers.recommendations import render_recommendations
+from speclogician.presentation.renderers.scenario_complement import render_scenario_complement
+
+
+def present_predicate(
+    p: StatePredicate | ActionPredicate,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_predicate_pm(p, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_predicate(pm, ctx=ctx)
+
+
+def present_transition(
+    t: Transition,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_transition_pm(t, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_transition(pm, ctx=ctx)
+
+
+def present_domain_model(
+    dm: DomainModel,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_domain_model_pm(dm, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_domain_model(pm, ctx=ctx)
+
+
+def present_spec(
+    spec: Spec,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_spec_pm(spec, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_spec(pm, ctx=ctx)
+
+
+def present_scenario_complement(
+    comp: ScenarioComplement,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_scenario_complement_pm(comp, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_scenario_complement(pm, ctx=ctx)
+
+
+def present_trace(
+    tr: TestTrace | LogTrace,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    if isinstance(tr, TestTrace):
+        pm = build_test_trace_pm(tr, ctx)
+        if json_only:
+            return pm.model_dump()
+        return render_test_trace(pm, ctx=ctx)
+
+    if isinstance(tr, LogTrace):
+        pm = build_log_trace_pm(tr, ctx)
+        if json_only:
+            return pm.model_dump()
+        return render_log_trace(pm, ctx=ctx)
+
+    raise TypeError(f"Unsupported trace type: {type(tr).__name__}")
+
+
+def present_data_artifact(
+    a: DocRef | SrcCodeRef,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    if isinstance(a, DocRef):
+        pm = build_doc_ref_pm(a, ctx)
+        if json_only:
+            return pm.model_dump()
+        return render_doc_ref(pm, ctx=ctx)
+
+    if isinstance(a, SrcCodeRef):
+        pm = build_src_code_ref_pm(a, ctx)
+        if json_only:
+            return pm.model_dump()
+        return render_src_code_ref(pm, ctx=ctx)
+
+    raise TypeError(f"Unsupported data artifact type: {type(a).__name__}")
+
+
+def present_artifact_container(
+    cont: ArtifactContainer,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_artifact_container_pm(cont, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_artifact_container(pm, ctx=ctx)
+
+
+def present_smart_find(
+    res: SmartFindResults,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_smart_find_pm(res, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_smart_find(pm, ctx=ctx)
+
+
+def present_state_diff(
+    sd: StateDiff,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_state_diff_pm(sd, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_state_diff(pm, ctx=ctx)
+
+
+def present_state_instance(
+    si: StateInstance,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_state_instance_pm(si, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_state_instance(pm, ctx=ctx)
+
+
+def present_scenario(
+    sc: Scenario,
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_scenario_pm(sc, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_scenario(pm, ctx=ctx)
+
+
+def present_instances_list(
+    states: list[StateInstance],
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_instances_list_pm(states, ctx)
+    if json_only:
+        return pm.model_dump()
+    return render_instances_list(pm, ctx=ctx)
+
+
+def present_recommendations(
+    recs: list[Recommendation],
+    *,
+    ctx: RenderCtx,
+    json_only: bool,
+):
+    pm = build_recommendations_pm(recs, ctx)
+    return pm.model_dump() if json_only else render_recommendations(pm, ctx=ctx)

speclogician/presentation/builders/_links.py

@@ -0,0 +1,44 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/presentation/builders/_links.py
+#
+
+from __future__ import annotations
+
+from speclogician.presentation.ctx import RenderCtx
+from speclogician.presentation.models.predicate import LinkedArtifactsPM
+from speclogician.data.traces import TestTrace, LogTrace
+from speclogician.data.refs import DocRef, SrcCodeRef
+
+
+def build_links_pm(comp_id: str, ctx: RenderCtx) -> LinkedArtifactsPM:
+    links = LinkedArtifactsPM()
+
+    if ctx.art_map is None:
+        return links
+
+    art_ids = list(ctx.art_map.get_arts_for_component(comp_id))
+    links.total = len(art_ids)
+    links.art_ids = art_ids if ctx.show_art_ids else []
+
+    if ctx.art_cont is None:
+        links.unresolved_ids = len(art_ids)
+        return links
+
+    unresolved = 0
+    for aid in art_ids:
+        a = ctx.art_cont.get_by_art_id(aid)
+        if a is None:
+            unresolved += 1
+        elif isinstance(a, TestTrace):
+            links.test_traces += 1
+        elif isinstance(a, LogTrace):
+            links.log_traces += 1
+        elif isinstance(a, DocRef):
+            links.doc_refs += 1
+        elif isinstance(a, SrcCodeRef):
+            links.src_code_refs += 1
+
+    links.unresolved_ids = unresolved
+    return links

speclogician/presentation/builders/container.py

@@ -0,0 +1,53 @@
+#
+#   Imandra Inc.
+#
+#   speclogician/presentation/builders/container.py
+#
+
+from __future__ import annotations
+
+from speclogician.data.container import ArtifactContainer
+from speclogician.presentation.ctx import RenderCtx
+
+from speclogician.presentation.models.container import (
+    ArtifactContainerPM,
+    ArtifactContainerCountsPM,
+    ArtifactContainerItemsPM,
+)
+
+from speclogician.presentation.builders.trace import build_test_trace_pm, build_log_trace_pm
+from speclogician.presentation.builders.data_artifact import build_doc_ref_pm, build_src_code_ref_pm
+
+
+def build_artifact_container_pm(cont: ArtifactContainer, ctx: RenderCtx) -> ArtifactContainerPM:
+    counts = ArtifactContainerCountsPM(
+        num_test_traces_total=cont.num_test_traces_total,
+        num_test_traces_matched=cont.num_test_traces_matched,
+        num_test_traces_logic_good=cont.num_test_traces_logic_good,
+        num_log_traces_total=cont.num_log_traces_total,
+        num_log_traces_matched=cont.num_log_traces_matched,
+        num_log_traces_logic_good=cont.num_log_traces_logic_good,
+        num_src_code_arts_total=cont.num_src_code_arts_total,
+        num_src_code_arts_matched=cont.num_src_code_arts_matched,
+        num_doc_arts_total=cont.num_doc_arts_total,
+        num_doc_arts_matched=cont.num_doc_arts_matched,
+    )
+
+    items = ArtifactContainerItemsPM()
+
+    if not ctx.show_stats_only:
+        if ctx.show_traces:
+            items.test_traces = [build_test_trace_pm(t, ctx) for t in cont.test_traces]
+            items.log_traces = [build_log_trace_pm(t, ctx) for t in cont.log_traces]
+        else:
+            items.test_traces = []
+            items.log_traces = []
+
+        if ctx.show_artifacts:
+            items.doc_refs = [build_doc_ref_pm(d, ctx) for d in cont.doc_ref]
+            items.src_code_refs = [build_src_code_ref_pm(s, ctx) for s in cont.src_code]
+        else:
+            items.doc_refs = []
+            items.src_code_refs = []
+
+    return ArtifactContainerPM(counts=counts, items=items)