coom-core 0.0.1a1__py3-none-any.whl

coom/check/__init__.py

@@ -0,0 +1,18 @@
+"""Static checks of a compiled model and detection of the profiles it uses.
+
+The checks decide whether a model is valid regardless of any configuration. They cover the typing of formulas,
+comparisons, assignments, table cells and test steps, values outside declared ranges, empty index ranges and
+structures that contain themselves.
+"""
+
+from coom.check._profiles import Profile, detect_profiles
+from coom.check._structure import check_structure
+from coom.check._typing import check_types
+from coom.diagnostics import Diagnostic
+from coom.model import Model
+
+__all__ = ["Profile", "check", "detect_profiles"]
+
+
+def check(model: Model) -> tuple[Diagnostic, ...]:
+    return (*check_structure(model), *check_types(model))

coom/check/_profiles.py

@@ -0,0 +1,147 @@
+"""Detection of the language profiles and modules a model uses."""
+
+from enum import StrEnum
+
+from coom.check._typing import AGGREGATES, formula_type, formulas
+from coom.model import (
+    Behavior,
+    Binary,
+    BinaryOp,
+    Call,
+    Combinations,
+    Compare,
+    Default,
+    Feature,
+    FeatureStep,
+    Formula,
+    IsDefined,
+    Model,
+    Numerical,
+    Optimize,
+    PathAccess,
+    Require,
+    Visibility,
+    parts,
+    walk,
+)
+
+
+class Profile(StrEnum):
+    """A profile or module of the language, CORE being the one every model uses."""
+
+    CORE = "CORE"
+    N_OUT = "N-OUT"
+    N_LIN = "N-LIN"
+    N_FULL = "N-FULL"
+    C_FIX = "C-FIX"
+    C_USER = "C-USER"
+    C_OPEN = "C-OPEN"
+    D_BASE = "D-BASE"
+    D_COND = "D-COND"
+    OPTIMIZE = "O"
+    UI = "UI"
+    TEST = "TEST"
+
+
+def detect_profiles(model: Model) -> tuple[Profile, ...]:
+    """Returns the smallest profile of each family that covers the model, in the order of the enumeration.
+
+    Numbers. N-OUT if no condition, constraint or table reads a number, so calculations stay outside the solution
+    space. Otherwise N-LIN if all arithmetic is linear, that is sums, differences, products and quotients with a
+    constant factor or divisor, and the aggregates. Otherwise N-FULL.
+
+    Cardinalities. C-FIX if every cardinality is fixed. C-OPEN if a cardinality is unbounded or a behavior aggregates
+    over or ranges across a feature whose number of instances varies, since then the reasoner decides that number.
+    Otherwise C-USER, where the user decides it.
+
+    Defaults. D-BASE if no default has a condition or an explicit priority, otherwise D-COND.
+    """
+    profiles = [Profile.CORE]
+    numbers = _numbers(model)
+    if numbers is not None:
+        profiles.append(numbers)
+    cardinalities = _cardinalities(model)
+    if cardinalities is not None:
+        profiles.append(cardinalities)
+    defaults = [behavior for behavior in model.behaviors if isinstance(behavior, Default)]
+    if defaults:
+        conditioned = any(default.conditions or default.priority is not None for default in defaults)
+        profiles.append(Profile.D_COND if conditioned else Profile.D_BASE)
+    if any(isinstance(behavior, Optimize) for behavior in model.behaviors):
+        profiles.append(Profile.OPTIMIZE)
+    if any(isinstance(behavior, Visibility) for behavior in model.behaviors):
+        profiles.append(Profile.UI)
+    if model.tests:
+        profiles.append(Profile.TEST)
+    return tuple(profiles)
+
+
+def _numbers(model: Model) -> Profile | None:
+    declared = any(isinstance(feature.type, Numerical) for feature in model.features()) or any(
+        isinstance(attribute.type, Numerical)
+        for enumeration in model.enumerations
+        for attribute in enumeration.attributes
+    )
+    if not declared:
+        return None
+    if not any(_reads_number(behavior) for behavior in model.behaviors):
+        return Profile.N_OUT
+    linear = all(_linear(formula) for behavior in model.behaviors for formula in formulas(behavior))
+    return Profile.N_LIN if linear else Profile.N_FULL
+
+
+def _reads_number(behavior: Behavior) -> bool:
+    """Whether a condition, constraint or table of the behavior depends on a numeric value."""
+    conditions = (*behavior.conditions, behavior.condition) if isinstance(behavior, Require) else behavior.conditions
+    tested: list[Formula] = list(behavior.columns) if isinstance(behavior, Combinations) else []
+    for node in walk(*conditions):
+        if isinstance(node, Compare):
+            tested += [node.left, node.right]
+        elif isinstance(node, IsDefined):
+            tested.append(node.formula)
+    return any(_is_number(formula) for formula in tested)
+
+
+def _is_number(formula: Formula) -> bool:
+    typed = formula_type(formula)
+    return typed is not None and isinstance(typed.base, Numerical)
+
+
+def _constant(formula: Formula) -> bool:
+    return not any(isinstance(node, PathAccess) for node in walk(formula))
+
+
+def _linear(formula: Formula) -> bool:
+    match formula:
+        case Binary(op=BinaryOp.MUL):
+            return _constant(formula.left) or _constant(formula.right)
+        case Binary(op=BinaryOp.DIV):
+            return _constant(formula.right)
+        case Binary(op=BinaryOp.POW):
+            return _constant(formula)
+        case Call():
+            return formula.function in AGGREGATES or _constant(formula)
+        case _:
+            return True
+
+
+def _cardinalities(model: Model) -> Profile | None:
+    varying = [feature for feature in model.features() if (feature.min, feature.max) != (1, 1)]
+    if not varying:
+        return None
+    if all(feature.min == feature.max for feature in varying):
+        return Profile.C_FIX
+    if any(feature.max is None for feature in varying):
+        return Profile.C_OPEN
+    ranged = {feature for feature in varying if feature.min != feature.max}
+    for behavior in model.behaviors:
+        for node in walk(*parts(behavior)):
+            if isinstance(node, Call) and node.function in AGGREGATES:
+                for argument in walk(*node.args):
+                    if isinstance(argument, PathAccess) and _ranges_over(argument, ranged):
+                        return Profile.C_OPEN
+    return Profile.C_USER
+
+
+def _ranges_over(access: PathAccess, ranged: set[Feature]) -> bool:
+    return any(isinstance(step, FeatureStep) and step.feature in ranged and step.is_range for step in access.path.steps)

coom/check/_structure.py

@@ -0,0 +1,35 @@
+"""Checks of the product hierarchy."""
+
+from collections.abc import Iterator
+
+from coom.diagnostics import Diagnostic, Severity
+from coom.model import Feature, Model, Structure
+
+
+def check_structure(model: Model) -> Iterator[Diagnostic]:
+    """Reports every structure that contains itself, which would require infinitely many instances to configure."""
+    reported: set[Structure] = set()
+    for structure in model.structures:
+        cycle = _cycle(structure, structure, [])
+        if cycle is None or structure in reported:
+            continue
+        reported.update(feature.owner for feature in cycle)
+        through = " > ".join(feature.qualified_name for feature in cycle)
+        yield Diagnostic(
+            Severity.ERROR, f"the structure {structure.name} contains itself through {through}", cycle[0].span
+        )
+
+
+def _cycle(start: Structure, current: Structure, trail: list[Feature]) -> list[Feature] | None:
+    """Returns the features that lead from the current structure back to the start, depth first."""
+    for feature in current.features:
+        if not isinstance(feature.type, Structure) or feature in trail:
+            continue
+        if feature.type is start:
+            return [*trail, feature]
+        if any(step.owner is feature.type for step in trail):
+            continue
+        found = _cycle(start, feature.type, [*trail, feature])
+        if found is not None:
+            return found
+    return None

coom/check/_typing.py

@@ -0,0 +1,315 @@
+"""Typing of formulas and the type rules of conditions, assignments, tables and tests."""
+
+from collections.abc import Iterator
+from decimal import Decimal
+from typing import NamedTuple, assert_never
+
+from coom.diagnostics import Diagnostic, Severity
+from coom.model import (
+    And,
+    Behavior,
+    Binary,
+    Boolean,
+    Call,
+    Combinations,
+    Compare,
+    CompareOp,
+    Condition,
+    Constant,
+    ConstantValue,
+    Default,
+    Enumeration,
+    FeatureStep,
+    Formula,
+    Function,
+    Imply,
+    IsAvailable,
+    IsBlocked,
+    IsDefined,
+    IsEmpty,
+    IsFixed,
+    IsHidden,
+    IsReadonly,
+    IsShown,
+    Model,
+    Negate,
+    Not,
+    Numerical,
+    Optimize,
+    Option,
+    Or,
+    Path,
+    PathAccess,
+    RemoveValue,
+    Require,
+    ResetValue,
+    SetValue,
+    Span,
+    Structure,
+    TestCase,
+    Textual,
+    Type,
+    Visibility,
+    parts,
+    type_name,
+    walk,
+)
+
+NUMBER = Numerical()
+"""The type of computed numbers, whose grid and bounds do not matter for typing."""
+
+AGGREGATES = frozenset({Function.COUNT, Function.SUM, Function.MIN, Function.MAX})
+EQUALITIES = frozenset({CompareOp.EQ, CompareOp.NE})
+
+
+class Typed(NamedTuple):
+    """The type of a formula, a collection if the formula may evaluate to several values."""
+
+    base: Type
+    collection: bool = False
+
+
+def describe(typed: Typed) -> str:
+    """Names the type for messages, such as "a number" or "a collection of options of Color"."""
+    match typed.base:
+        case Numerical():
+            single, plural = "a number", "numbers"
+        case Textual():
+            single, plural = "a text", "texts"
+        case Boolean():
+            single, plural = "a truth value", "truth values"
+        case Enumeration():
+            single, plural = f"an option of {typed.base.name}", f"options of {typed.base.name}"
+        case Structure():
+            name = "the product" if typed.base.is_root else typed.base.name
+            single, plural = f"an instance of {name}", f"instances of {name}"
+        case _:
+            assert_never(typed.base)
+    return f"a collection of {plural}" if typed.collection else single
+
+
+def comparable(op: CompareOp, left: Type, right: Type) -> bool:
+    """Whether values of the two types can be compared by the operator, ignoring collections."""
+    match left, right:
+        case (Numerical(), Numerical()) | (Textual(), Textual()):
+            return True
+        case Enumeration(), Enumeration():
+            return left is right
+        case (Boolean(), Boolean()):
+            return op in EQUALITIES
+        case Structure(), Structure():
+            return left is right and op in EQUALITIES
+        case _:
+            return False
+
+
+def constant_type(value: ConstantValue) -> Type:
+    match value:
+        case bool():
+            return Boolean()
+        case Decimal():
+            return NUMBER
+        case str():
+            return Textual()
+        case Option():
+            return value.owner
+        case _:
+            assert_never(value)
+
+
+def in_range(numerical: Numerical, value: Decimal) -> bool:
+    return (numerical.min is None or value >= numerical.min) and (numerical.max is None or value <= numerical.max)
+
+
+class TypeChecker:
+    """Infers the types of formulas and reports where the type rules of the language are violated."""
+
+    def __init__(self) -> None:
+        self.diagnostics: list[Diagnostic] = []
+
+    def error(self, span: Span | None, message: str) -> None:
+        self.diagnostics.append(Diagnostic(Severity.ERROR, message, span))
+
+    # Formulas
+
+    def formula(self, formula: Formula) -> Typed | None:
+        """Returns the type of a formula, or None if it has a type error that is already reported."""
+        match formula:
+            case Constant():
+                return Typed(constant_type(formula.value))
+            case PathAccess():
+                self.path(formula.path)
+                return Typed(formula.path.type, formula.path.is_range)
+            case Negate():
+                return Typed(NUMBER) if self.number(formula.operand) else None
+            case Binary():
+                left, right = self.number(formula.left), self.number(formula.right)
+                return Typed(NUMBER) if left and right else None
+            case Call():
+                return self._call(formula)
+            case _:
+                assert_never(formula)
+
+    def number(self, formula: Formula) -> bool:
+        """Checks that a formula is a single number, as arithmetic requires."""
+        typed = self.formula(formula)
+        if typed is None:
+            return False
+        if typed.collection:
+            self.error(formula.span, f"arithmetic needs a single number, not {describe(typed)}")
+            return False
+        if not isinstance(typed.base, Numerical):
+            self.error(formula.span, f"arithmetic needs a number, not {describe(typed)}")
+            return False
+        return True
+
+    def _call(self, call: Call) -> Typed | None:
+        if call.function not in AGGREGATES:
+            valid = [self.number(argument) for argument in call.args]
+            return Typed(NUMBER) if all(valid) else None
+        types = [self.formula(argument) for argument in call.args]
+        if any(typed is None for typed in types):
+            return None
+        bases = [typed.base for typed in types if typed is not None]
+        match call.function:
+            case Function.COUNT:
+                return Typed(NUMBER)
+            case Function.SUM:
+                if not all(isinstance(base, Numerical) for base in bases):
+                    self.error(call.span, "sum needs numbers")
+                    return None
+                return Typed(NUMBER)
+            case _:
+                first = bases[0]
+                if not all(comparable(CompareOp.LT, first, other) for other in bases):
+                    self.error(call.span, f"{call.function} needs values that can be ordered against each other")
+                    return None
+                return Typed(NUMBER if isinstance(first, Numerical) else first)
+
+    def path(self, path: Path) -> None:
+        for step in path.steps:
+            index = step.index if isinstance(step, FeatureStep) else None
+            if index is not None and (index.first >= 0) == (index.last >= 0) and index.first > index.last:
+                self.error(step.span, f"the index range [{index}] is empty")
+
+    # Conditions
+
+    def condition(self, condition: Condition) -> None:
+        match condition:
+            case Compare():
+                self.compare(condition.op, condition.left, condition.right, condition.span)
+            case IsDefined():
+                self.formula(condition.formula)
+            case Not():
+                self.condition(condition.operand)
+            case And() | Or():
+                for operand in condition.operands:
+                    self.condition(operand)
+            case Constant():
+                pass
+            case _:
+                assert_never(condition)
+
+    def compare(self, op: CompareOp, left: Formula, right: Formula, span: Span | None) -> None:
+        left_type, right_type = self.formula(left), self.formula(right)
+        if left_type is None or right_type is None:
+            return
+        if left_type.collection and right_type.collection:
+            self.error(span, "cannot compare two collections with each other")
+        elif not comparable(op, left_type.base, right_type.base):
+            self.error(span, f"cannot compare {describe(left_type)} with {describe(right_type)} by {op}")
+
+    # Assignments
+
+    def assignment(self, target: Path, value: Formula, span: Span | None) -> None:
+        """Checks a value written to a feature, by imply, default or a test step."""
+        self.path(target)
+        if isinstance(target.type, Structure):
+            self.error(span, f"cannot assign a value to the structure feature {target}")
+            return
+        typed = self.formula(value)
+        if typed is None:
+            return
+        if typed.collection:
+            self.error(value.span, f"cannot assign {describe(typed)} to {target}")
+        elif not comparable(CompareOp.EQ, target.type, typed.base):
+            self.error(value.span, f"cannot assign {describe(typed)} to {target}, which holds {type_name(target.type)}")
+        elif (
+            isinstance(value, Constant)
+            and isinstance(value.value, Decimal)
+            and isinstance(target.type, Numerical)
+            and not in_range(target.type, value.value)
+        ):
+            self.error(value.span, f"{value.value} is outside the range {type_name(target.type)} of {target}")
+
+    # Model items
+
+    def behavior(self, behavior: Behavior) -> None:
+        for condition in behavior.conditions:
+            self.condition(condition)
+        match behavior:
+            case Require():
+                self.condition(behavior.condition)
+            case Imply() | Default():
+                self.assignment(behavior.target, behavior.value, behavior.span)
+            case Optimize():
+                self.path(behavior.target)
+                if not isinstance(behavior.target.type, Numerical):
+                    self.error(behavior.span, f"{behavior.direction} needs a numeric feature, not {behavior.target}")
+            case Visibility():
+                self.path(behavior.target)
+            case Combinations():
+                for column in behavior.columns:
+                    self.formula(column)
+                for row in behavior.rows:
+                    for column, cell in zip(behavior.columns, row.cells, strict=True):
+                        for atom in cell or ():
+                            self.compare(atom.op, column, atom.value, atom.span)
+            case _:
+                assert_never(behavior)
+
+    def test(self, test: TestCase) -> None:
+        for step in test.steps:
+            match step:
+                case SetValue() | IsFixed() | IsShown() | IsAvailable() | IsBlocked() | IsHidden():
+                    if step.value is None:
+                        self.path(step.path)
+                    else:
+                        self.assignment(step.path, step.value, step.span)
+                case RemoveValue() | ResetValue() | IsEmpty() | IsReadonly():
+                    self.path(step.path)
+                case _:
+                    assert_never(step)
+
+    def options(self, enumeration: Enumeration) -> None:
+        for option in enumeration.options:
+            for attribute, value in option.values.items():
+                numerical = attribute.type
+                if isinstance(numerical, Numerical) and isinstance(value, Decimal) and not in_range(numerical, value):
+                    self.error(
+                        option.span,
+                        f"{value} is outside the range {type_name(numerical)} of the attribute {attribute.name}",
+                    )
+
+
+def check_types(model: Model) -> Iterator[Diagnostic]:
+    checker = TypeChecker()
+    for enumeration in model.enumerations:
+        checker.options(enumeration)
+    for behavior in model.behaviors:
+        checker.behavior(behavior)
+    for test in model.tests:
+        checker.test(test)
+    yield from checker.diagnostics
+
+
+def formula_type(formula: Formula) -> Typed | None:
+    """Returns the type of a formula without reporting, None if the formula has a type error."""
+    return TypeChecker().formula(formula)
+
+
+def formulas(item: Behavior | TestCase) -> Iterator[Formula]:
+    """Yields every formula of a behavior or test, nested ones included."""
+    for node in walk(*parts(item)):
+        if isinstance(node, Constant | PathAccess | Negate | Binary | Call):
+            yield node

coom/configuration/__init__.py

@@ -0,0 +1,30 @@
+"""Configurations of a model and their evaluation.
+
+A configuration is a tree of instances below the instance of the product. Every feature of an instance has numbered
+slots from 0 up to the maximum cardinality, and each slot is empty or holds an assignment, a value together with the
+role that says why it is there. A structure feature holds instances, which then belong to that slot. Numbers are
+stored as decimals on the grid of their feature, rounded half away from zero when they are assigned. Options, truth
+values and texts are stored as the Option, bool and str objects of the model.
+
+The evaluate module decides the truth of conditions and behaviors in a configuration, and the arithmetic module
+defines the exact calculation both rely on. The visibility module says which values a user interface hides or locks.
+Their main entry points are re-exported here.
+"""
+
+from coom.configuration._configuration import Assignment, Configuration, Instance, Role, Value
+from coom.configuration.evaluate import Truth, Verdict, truth, verdicts
+from coom.configuration.visibility import Visibilities, visibilities
+
+__all__ = [
+    "Assignment",
+    "Configuration",
+    "Instance",
+    "Role",
+    "Truth",
+    "Value",
+    "Verdict",
+    "Visibilities",
+    "truth",
+    "verdicts",
+    "visibilities",
+]