orchestrata_ultimate.openspec.models

Reference › orchestrata_ultimate › openspec › models

models holds the plain dataclasses of the OpenSpec support package (SPEC-104), with no I/O and no internal imports. Scenario is a named scenario with its WHEN and THEN lines. Requirement is a title, a SHALL statement and its scenarios. OpenSpecDoc is a parsed capability spec: a capability name, a purpose and a list of requirements. Delta is a change block whose operation is one of ADDED, MODIFIED, REMOVED or RENAMED (DeltaOp). SpecFolder is the result of locating a spec folder: its root, a SpecFormat of openspec, orchestrata or unknown, and the capabilities and changes found. parse builds these from markdown, render writes them back, detect produces SpecFolder, and repo uses all of them.

At a glance

Class diagram

Dependency diagram

API

Classes

Scenario (dataclass)

Decorators: dataclass · Line 20

A single OpenSpec scenario (#### Scenario: with WHEN/THEN bullets).

Requirement (dataclass)

Decorators: dataclass · Line 28

An OpenSpec requirement (### Requirement: + a SHALL statement).

OpenSpecDoc (dataclass)

Decorators: dataclass · Line 37

A parsed OpenSpec capability spec (specs/<capability>/spec.md).

Delta (dataclass)

Decorators: dataclass · Line 46

A change-delta block (## ADDED|MODIFIED|REMOVED|RENAMED Requirements).

SpecFolder (dataclass)

Decorators: dataclass · Line 54

The result of locating a project's spec folder.

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/openspec/models.py

"""OpenSpec data models (SPEC-104).

Plain dataclasses representing the structure of an OpenSpec capability spec and
a change delta. Pure data — no I/O. See :mod:`orchestrata_ultimate.openspec.parse`
(markdown -> models) and :mod:`orchestrata_ultimate.openspec.render` (models ->
markdown).
"""

from __future__ import annotations

from dataclasses import dataclass, field
from pathlib import Path
from typing import Literal

SpecFormat = Literal["openspec", "orchestrata", "unknown"]
DeltaOp = Literal["ADDED", "MODIFIED", "REMOVED", "RENAMED"]


@dataclass
class Scenario:
    """A single OpenSpec scenario (``#### Scenario:`` with WHEN/THEN bullets)."""

    name: str
    lines: list[str] = field(default_factory=list)  # e.g. ["- **WHEN** ...", ...]


@dataclass
class Requirement:
    """An OpenSpec requirement (``### Requirement:`` + a SHALL statement)."""

    title: str
    text: str = ""  # the SHALL statement body
    scenarios: list[Scenario] = field(default_factory=list)


@dataclass
class OpenSpecDoc:
    """A parsed OpenSpec capability spec (``specs/<capability>/spec.md``)."""

    capability: str = ""
    purpose: str = ""
    requirements: list[Requirement] = field(default_factory=list)


@dataclass
class Delta:
    """A change-delta block (``## ADDED|MODIFIED|REMOVED|RENAMED Requirements``)."""

    operation: DeltaOp
    requirements: list[Requirement] = field(default_factory=list)


@dataclass
class SpecFolder:
    """The result of locating a project's spec folder."""

    root: Path | None
    format: SpecFormat = "unknown"
    capabilities: list[str] = field(default_factory=list)
    changes: list[str] = field(default_factory=list)