include-checks is advertised but ignored; severity-levels has no input

[reuvenharrison]

Summary

The actions advertise include-checks, which current oasdiff ignores, and do not expose severity-levels, which replaced it. So the documented way to enable an optional check silently does nothing, and the working way is not reachable from an action input.

include-checks is ignored

oasdiff deprecated the flag and now ignores it, pointing at --severity-levels instead:

"include-checks": "it is now ignored; use --severity-levels to enforce a check as breaking"

The actions still advertise it as a supported input. From the README:

input	default	description
include-checks	''	Include optional breaking change checks

It is also still passed through in action.yml and the entrypoints. A user who sets it gets no error and no effect, which is the worst of the three possible outcomes: they believe a check is enabled when it is not, and a check they wanted enforced never fires.

This came up while closing #154. The version-bump checks there are exactly the sort of thing someone would reach for include-checks to enable, and they would silently get nothing.

severity-levels is only reachable through a config file

The replacement works from an action today, but only via .oasdiff.yaml:

# .oasdiff.yaml
severity-levels: oasdiff-levels.txt
fail-on: ERR

That is fine as a mechanism, and worth keeping. But every other commonly used oasdiff flag has a first-class input, so the one flag that controls which changes fail the build being config-file-only is a surprising gap, and it is undiscoverable from the action docs.

Proposal

1. Add a severity-levels input to the actions that take one (breaking, changelog, diff, pr-comment), passed through to --severity-levels, documented in the README alongside fail-on.
2. Deal with include-checks. Either drop the input, or keep it and emit a deprecation annotation naming severity-levels, so an existing workflow that sets it is told rather than silently ignored. A warning annotation is probably the kinder first step, since removing the input outright breaks workflows that currently pass it harmlessly.
3. Update the README, which currently documents include-checks as functional.

Note

Whatever is decided for the actions, the underlying flag's behaviour is oasdiff's, not the actions'. This issue is only about the actions advertising a flag that no longer does anything and not surfacing the one that replaced it.

[reuvenharrison]

Correcting the second half of this issue, which I got wrong.

I claimed "every other commonly used oasdiff flag has a first-class input, so the one flag that controls which changes fail the build being config-file-only is a surprising gap." That is not true. Counting breaking:

	count	examples
oasdiff flags with an input	10	fail-on, composed, err-ignore
oasdiff flags without	20	auto-upgrade, stability-level, match-path, prefix-base, format, lang, template

Not having an input is the norm, not the anomaly, and severity-levels already worked through .oasdiff.yaml with no code change.

Decision: .oasdiff.yaml is the configuration surface the actions converge on, and the input list stops growing. Adding severity-levels would have grown a surface we intend to freeze, and every input is another positional argument in a scheme where a mis-ordered index corrupts a run silently rather than erroring. Proposal 1 in this issue is therefore declined on purpose, not overlooked.

Proposals 2 and 3 stand and are what #197 does: the action stops forwarding include-checks, warns and names .oasdiff.yaml as the replacement, and the README stops documenting the flag as functional. The config path also gains a test, alongside the existing .oasdiff.yaml jobs for fail-on and err-ignore.