API and report reference

Public Python API

from cwl_baseline import BaselineOptions, baseline, baseline_plugin

# previous and current are TranspilerContext objects supplied by the host.
report = baseline(previous, current, review_bump=None)

# Resolve previous through current.resolver and write a report.
baseline_plugin.execute(
    current,
    BaselineOptions(previous="release.cwl", output="baseline.json", check=True),
)

baseline(previous, current, *, review_bump=None) returns BaselineReport. baseline_plugin.execute(context, options) returns None and writes JSON. Both compare all Processes in the contexts, using each context's metadata.software_version.

Plugin options

Option Type / default Meaning
previous Nonempty string, required Passed unchanged to context.resolver.resolve()
output Path, baseline.json Destination; parent directory must exist
check Boolean, false Fail on unresolved review or insufficient version
review_bump patch, minor, major, or None Global classification of review findings

Unknown options are rejected. The runtime CLI uses --review-bump for review_bump and --check / --no-check for check.

Report fields

Field Meaning
schema_version Report format version, currently 1.0
previous_version, current_version Compared SemVer metadata
minimum_bump Maximum static floor: none, patch, minor, or major
minimum_version Previous version incremented once by that floor
suggested_version Version after review classification, or null while unresolved
review_required Whether any review remains unresolved
review_bump Supplied global classification, or null
declared_version_sufficient Review is resolved and current version meets the suggestion
findings Detailed changes contributing to the decision

Each finding contains rule, path, category, minimum_bump, review_required, message, before, after, before_present, and after_present. Categories are interface, environment, behavior, and metadata. Paths use JSON-Pointer-style escaping in the normalized model. Presence flags distinguish missing values from null. Original finding review flags remain true after global classification for audit.

The suggestion is a minimum release, not an instruction to downgrade an already higher version. See policy for aggregation, prereleases, and the meaning of unresolved review.

Errors

  • PluginFailureError: domain failures, including invalid version metadata, ambiguous/duplicate identities, unresolved review or insufficient version under check.
  • PluginExecutionError: unexpected resolver errors or report write failures.
  • Resolver PluginError exceptions propagate unchanged.
  • Invalid options raise Pydantic validation errors.

Check failures occur after the report is written. Failures during resolution or comparison may prevent a report from being produced.

Implementation reference

Compare all declared Processes, taking the maximum bump exactly once.

Source code in src/cwl_baseline/compare.py
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
def baseline(
    previous: TranspilerContext,
    current: TranspilerContext,
    *,
    review_bump: Literal["patch", "minor", "major"] | None = None,
) -> BaselineReport:
    """Compare all declared Processes, taking the maximum bump exactly once."""
    old_version = parse_version(previous.metadata.software_version, "Previous")
    new_version = parse_version(current.metadata.software_version, "Current")
    if old_version.prerelease is not None:
        raise PluginFailureError(
            "The comparison baseline must be a released version, not a prerelease."
        )
    old, new = document(previous), document(current)
    if not old:
        raise PluginFailureError("The previous document contains no Processes.")
    comparator = Comparator()
    for name in sorted(old.keys() | new.keys()):
        path = path_join("/processes", name)
        if name not in new:
            comparator.add(
                Finding(
                    category=FindingCategory.INTERFACE,
                    rule="process.removed",
                    path=path,
                    minimum_bump=Bump.MAJOR,
                    message="Public Process removed.",
                ),
                old[name],
                MISSING,
            )
        elif name not in old:
            comparator.add(
                Finding(
                    category=FindingCategory.INTERFACE,
                    rule="process.added",
                    path=path,
                    minimum_bump=Bump.MINOR,
                    message="Public Process added.",
                ),
                MISSING,
                new[name],
            )
        else:
            comparator.process(old[name], new[name], path)
    findings = comparator.findings
    minimum = max(
        (f.minimum_bump for f in findings),
        key=BUMP_PRIORITY.__getitem__,
        default=Bump.NONE,
    )
    classified_bump = Bump(review_bump) if review_bump is not None else None
    reviews = any(f.review_required for f in findings)
    effective = (
        max(minimum, classified_bump, key=BUMP_PRIORITY.__getitem__)
        if reviews and classified_bump is not None
        else minimum
    )
    unresolved = reviews and review_bump is None
    minimum_version = increment(old_version, minimum)
    suggestion = None if unresolved else increment(old_version, effective)
    return BaselineReport(
        previous_version=str(old_version),
        current_version=str(new_version),
        minimum_bump=minimum,
        minimum_version=str(minimum_version),
        suggested_version=str(suggestion) if suggestion is not None else None,
        review_required=unresolved,
        review_bump=classified_bump,
        declared_version_sufficient=not unresolved
        and new_version >= (suggestion or minimum_version),
        findings=findings,
    )

Bases: BaseModel

Source code in src/cwl_baseline/plugin.py
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
class BaselineOptions(BaseModel):
    model_config = ConfigDict(extra="forbid")

    previous: str = Field(
        min_length=1,
        description="Previous release location accepted by the context resolver",
    )
    output: Path = Field(default=Path("baseline.json"), description="JSON report destination")
    check: bool = Field(
        default=False,
        description="Fail if review is unresolved or the declared version is insufficient",
    )
    review_bump: Literal["patch", "minor", "major"] | None = Field(
        default=None,
        description="Explicit classification of all changes requiring behavioral review",
    )

Bases: BaseModel

CWL baseline comparison report. Required fields and defaults follow cwl_baseline.models.BaselineReport; the plugin serializes all fields, including defaults.

Source code in src/cwl_baseline/models.py
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
class BaselineReport(BaseModel):
    """
    CWL baseline comparison report. Required fields and defaults follow cwl_baseline.models.BaselineReport; the plugin serializes all fields, including defaults.
    """

    model_config = ConfigDict(
        extra="allow",
        populate_by_name=True,
    )
    schema_version: Annotated[str | None, Field(title="Schema Version")] = "1.0"
    """
    Report format version, currently 1.0.
    """
    previous_version: Annotated[str, Field(title="Previous Version")]
    """
    Semantic version of the previous released baseline.
    """
    current_version: Annotated[str, Field(title="Current Version")]
    """
    Declared semantic version of the current release.
    """
    minimum_bump: Bump
    minimum_version: Annotated[str, Field(title="Minimum Version")]
    """
    Previous version incremented once by minimum_bump.
    """
    suggested_version: Annotated[str | None, Field(title="Suggested Version")]
    """
    Minimum release version after review classification, or null while review remains unresolved.
    """
    review_required: Annotated[bool, Field(title="Review Required")]
    """
    Whether any behavioral review remains unresolved.
    """
    review_bump: Annotated[Bump | None, Field(title="Review Bump")] = None
    """
    Explicit global classification of changes requiring review, or null if none was supplied.
    """
    declared_version_sufficient: Annotated[bool, Field(title="Declared Version Sufficient")]
    """
    True when review is resolved and the current version meets or exceeds the suggested version.
    """
    findings: Annotated[list[Finding], Field(title="Findings", default_factory=list)]
    """
    Detailed changes contributing to the comparison; defaults to an empty list in the model.
    """

current_version instance-attribute

Declared semantic version of the current release.

declared_version_sufficient instance-attribute

True when review is resolved and the current version meets or exceeds the suggested version.

findings instance-attribute

Detailed changes contributing to the comparison; defaults to an empty list in the model.

minimum_version instance-attribute

Previous version incremented once by minimum_bump.

previous_version instance-attribute

Semantic version of the previous released baseline.

review_bump = None class-attribute instance-attribute

Explicit global classification of changes requiring review, or null if none was supplied.

review_required instance-attribute

Whether any behavioral review remains unresolved.

schema_version = '1.0' class-attribute instance-attribute

Report format version, currently 1.0.

suggested_version instance-attribute

Minimum release version after review classification, or null while review remains unresolved.

Bases: BaseModel

One detected change in the normalized CWL public contract.

Source code in src/cwl_baseline/models.py
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
class Finding(BaseModel):
    """
    One detected change in the normalized CWL public contract.
    """

    model_config = ConfigDict(
        extra="allow",
        populate_by_name=True,
    )
    rule: Annotated[str, Field(title="Rule")]
    """
    Identifier of the comparison rule that produced this finding.
    """
    path: Annotated[str, Field(title="Path")]
    """
    Location in the normalized model, using JSON-Pointer-style escaping.
    """
    category: FindingCategory
    minimum_bump: Bump
    review_required: Annotated[bool | None, Field(title="Review Required")] = False
    """
    Whether this finding needs behavioral review; retained for auditing after global review classification.
    """
    message: Annotated[str, Field(title="Message")]
    """
    Human-readable explanation of the change.
    """
    before: Annotated[Any | None, Field(title="Before")] = None
    """
    Previous JSON value; null also represents an absent value when before_present is false.
    """
    after: Annotated[Any | None, Field(title="After")] = None
    """
    Current JSON value; null also represents an absent value when after_present is false.
    """
    before_present: Annotated[bool | None, Field(title="Before Present")] = True
    """
    Whether the previous value exists, distinguishing absence from explicit null.
    """
    after_present: Annotated[bool | None, Field(title="After Present")] = True
    """
    Whether the current value exists, distinguishing absence from explicit null.
    """

after = None class-attribute instance-attribute

Current JSON value; null also represents an absent value when after_present is false.

after_present = True class-attribute instance-attribute

Whether the current value exists, distinguishing absence from explicit null.

before = None class-attribute instance-attribute

Previous JSON value; null also represents an absent value when before_present is false.

before_present = True class-attribute instance-attribute

Whether the previous value exists, distinguishing absence from explicit null.

message instance-attribute

Human-readable explanation of the change.

path instance-attribute

Location in the normalized model, using JSON-Pointer-style escaping.

review_required = False class-attribute instance-attribute

Whether this finding needs behavioral review; retained for auditing after global review classification.

rule instance-attribute

Identifier of the comparison rule that produced this finding.