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 undercheck.PluginExecutionError: unexpected resolver errors or report write failures.- Resolver
PluginErrorexceptions 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 | |
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 | |
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 | |
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 | |
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.