orchestrata_ultimate.core.base.traces

Reference › orchestrata_ultimate › core › base › traces

The @traces decorator, which ties a class or function to a specification, a user story and requirement ids. It is the most widely imported module in the project: nearly every package, among them agents, kernel, gateway and gates, uses it to annotate code, so the requirements traceability matrix can be built from the source (see the core narrative). It sits in the base layer with no project imports, and it was moved here from core.tracing.traceability to remove upward imports from layer 0.

traces(spec, story, reqs) returns a decorator that attaches the values to the target as a __traces__ attribute and returns the target itself. It raises ValueError when reqs is empty or when any id fails _validate_req_id, which accepts the REQ- patterns and US-NNN-NNN story ids. The scanners in tracing.scanner read the same annotations from the syntax tree without importing the code.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

Truncated at 25 nodes: showing 0 of 0 imports and 24 of 516 importers.

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/core/base/traces.py

"""Traceability decorator — layer-0 safe.

Provides the @traces decorator used to annotate classes and functions
with specification, story, and requirement IDs.  Zero external imports
(moves here from core.tracing.traceability to eliminate layer-0 upward
imports).
"""

from __future__ import annotations

import re
from collections.abc import Callable
from typing import TypeVar

T = TypeVar("T")

_REQ_ID_PATTERN = re.compile(
    r"^REQ-\d{3}-(?:\d{3}(?:-\d{3})?|[A-Z]{2,4}\d*-\d{3}|[A-Z]{2,4}-\d{3}-\d{3}|C\d+|Exit-Criteria-for-Th-\d{3})$"
)
_US_ID_PATTERN = re.compile(r"^US-\d{3}-\d{3}$")


def _validate_req_id(req_id: str) -> bool:
    """Check if a requirement ID matches the expected format."""
    return bool(_REQ_ID_PATTERN.match(req_id) or _US_ID_PATTERN.match(req_id))


def traces(
    spec: str = "",
    story: str = "",
    reqs: list[str] | None = None,
) -> Callable[[T], T]:
    """Decorator that annotates classes/methods with requirement traceability.

    Args:
        spec: Specification ID (e.g., "001", "002").
        story: User story ID (e.g., "US-001", "US-002").
        reqs: List of requirement IDs (e.g., ["REQ-001-001-001"]).

    Returns:
        The original class/function with __traces__ attribute attached.

    Raises:
        ValueError: If reqs is empty or contains invalid IDs.
    """
    if reqs is None:
        reqs = []

    if not reqs:
        raise ValueError("@traces requires at least one requirement ID in reqs=[]")

    for req_id in reqs:
        if not _validate_req_id(req_id):
            raise ValueError(
                f"Invalid requirement ID format: '{req_id}'. "
                f"Expected REQ-NNN-NNN[-NNN], REQ-NNN-ACn-NNN, REQ-NNN-FRn-NNN, "
                f"REQ-NNN-USn-NNN, REQ-NNN-NFRn-NNN, REQ-NNN-Cn (cluster/phase id, "
                f"e.g. REQ-033-C1), or US-NNN-NNN."
            )

    def decorator(obj: T) -> T:
        existing = getattr(obj, "__traces__", None)
        new_entry = {"spec": spec, "story": story, "reqs": list(reqs)}
        if existing is None:
            obj.__traces__ = new_entry  # type: ignore[attr-defined]
        elif isinstance(existing, list):
            existing.append(new_entry)
        else:
            obj.__traces__ = [existing, new_entry]  # type: ignore[attr-defined]
        return obj

    return decorator