Skip to content

fix: require whole-word skip and a non-empty reason in example annotations - #767

Open
Ectsang wants to merge 2 commits into
Universal-Commerce-Protocol:mainfrom
Ectsang:fix/skip-annotation-guard
Open

fix: require whole-word skip and a non-empty reason in example annotations#767
Ectsang wants to merge 2 commits into
Universal-Commerce-Protocol:mainfrom
Ectsang:fix/skip-annotation-guard

Conversation

@Ectsang

@Ectsang Ectsang commented Aug 25, 2026

Copy link
Copy Markdown

parse_annotation() treats any annotation text beginning with skip as a skip:

if text.startswith("skip"):

So skiped, skip_the_check and skipping validation for now each disable validation for that block, silently. _KNOWN_ATTRS catches the same class of typo on the validating path (shema=, directon=), but the skipping path has no guard. A typo that accidentally validates is loud; one that accidentally skips is invisible.

The reason field looks like it's there so every skip stays auditable, but it's optional in the parse — a bare skip returns {"skip": True, "reason": ""}.

Nothing is broken today. All 51 skip annotations in the docs use the documented skip reason="..." form. This is a guard against a future silent loss of coverage, not a live bug.

The fix matches skip as a whole word and returns the existing _error when reason is missing or empty. process_block already handles _error ahead of the skip branch, so nothing else changes.

Tested: all 51 live skip annotations still parse as skips. scripts/test_validate_examples.py goes from 42 to 47 passing, with the same two pre-existing failures (ucp-schema not on PATH).

…tions

parse_annotation() treated any text beginning with "skip" as a skip, so
skiped, skip_the_check and skipping validation for now each disabled
validation for that block silently. _KNOWN_ATTRS catches the same class of
typo on the validating path; the skipping path had no guard.

reason was also optional in the parse, so a bare skip returned an empty
reason and the skip was not auditable.

Match skip as a whole word and return the existing _error when reason is
missing or empty. process_block already handles _error ahead of the skip
branch, so nothing else changes.

All 51 skip annotations currently in the docs still parse as skips.
@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Aug 25, 2026
@carolinerg1 carolinerg1 added status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 25, 2026
Two CI checks failed on the whole-word skip guard:

- spellcheck flagged `skiped`, a deliberate typo used as test input.
  Appended it to the existing `# cspell:ignore` directive in both files
  rather than adding a misspelling to .cspell/custom-words.txt, which
  would silence genuine typos repo-wide.
- PYTHON_RUFF_FORMAT wanted the typo tuple wrapped its own way.

No behavior change. Contract tests unchanged: 47 pass, and the 2
failures (`ucp-schema` binary absent locally) are identical with and
without this commit.
@damaz91 damaz91 added the devops label Aug 26, 2026
@damaz91
damaz91 requested review from carolinerg1 and damaz91 and removed request for DanielFalconGuedes and jingyli August 26, 2026 17:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants